> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API 참조

> VoiceCheap REST API에 대한 전체 참조

# API 참조

VoiceCheap API는 표준 HTTP 메서드와 상태 코드를 사용합니다. 대부분의 엔드포인트는 JSON을 반환하고, 전사 내보내기는 SRT 또는 VTT도 반환할 수 있습니다.

계정 설정, 팀 관리, 미디어 도구 및 기타 워크플로에는 [작업 카탈로그](https://api-docs.voicecheap.ai/docs/ko/api-reference/actions.md)를 사용하세요. 이러한 워크플로는 [계정 MCP 서버](https://api-docs.voicecheap.ai/docs/ko/ai/model-context-protocol.md)에서도 사용할 수 있습니다. 단, 웹훅 서명 비밀 키 생성과 교체에는 REST가 필요합니다. [연동](https://api-docs.voicecheap.ai/docs/ko/ai/integrations.md)에서 자격 증명을 관리하고 [사용 제한](https://api-docs.voicecheap.ai/docs/ko/api-reference/limits.md)을 확인하세요.

## 기본 URL

모든 API 요청은 다음 주소로 보내야 합니다:

```text theme={null}
https://api.voicecheap.ai
```

## 인증

비공개 REST 호출은 `x-api-key` 또는 `Authorization: Bearer`의 API 키로 인증하세요. OpenAPI 문서는 공개되어 있습니다. 권한 범위가 지정된 자격 증명과 MCP용 OAuth는 [인증](https://api-docs.voicecheap.ai/docs/ko/authentication.md)을 참고하세요.

## JSON 작업 API

계정, 팀, 프로젝트, 음성 및 미디어 도구 섹션에서 각 JSON 작업을 개별적으로 설명합니다. 이 경로들은 조회와 삭제를 포함하여 모두 `POST`를 사용합니다. 인수는 JSON 본문으로 보내세요. 아래의 파일 업로드 및 기존 프로젝트 경로는 각자의 HTTP 메서드를 유지합니다.

`account:read` 권한이 있는 API 키를 만들고 `VOICECHEAP_API_KEY` 환경 변수를 설정한 다음 이 읽기 전용 요청을 실행하세요.

```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/account_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

완료된 작업은 HTTP 200과 함께 `data`에 결과를 반환합니다. 오래 걸리는 작업은 HTTP 202와 `requestId`를 반환합니다. [요청 상태](https://api-docs.voicecheap.ai/docs/ko/api-reference/actions/requests/action-request-get.md)를 조회하여 결과를 가져오세요. 작업 요청이 완료된 후에도 미디어 처리가 계속될 수 있습니다.

[분야별 전체 작업](https://api-docs.voicecheap.ai/docs/ko/api-reference/actions.md)을 살펴보거나 [키에 허용된 작업과 스키마](https://api-docs.voicecheap.ai/docs/ko/api-reference/discovery/actions-list.md)를 확인하세요. 각 페이지에 권한, 매개변수, 예제 및 오류가 설명되어 있습니다.

## 콘텐츠 유형

* **요청**: 파일 업로드에는 `multipart/form-data`을, 기타 요청에는 `application/json`을 사용하십시오.
* **응답**: JSON 엔드포인트는 `application/json`을 반환합니다. 대본 내보내기는 SRT 또는 VTT 텍스트를 반환할 수도 있습니다.

## 파일 업로드 및 기존 프로젝트 경로

> [card] [미디어 전사](https://api-docs.voicecheap.ai/docs/ko/api-reference/transcribe.md)
>
> `POST /v1/transcribe`
>
> 업로드된 파일을 JSON, SRT 또는 VTT로 전사합니다.

> [card] [프로젝트 대본 내보내기](https://api-docs.voicecheap.ai/docs/ko/api-reference/project-transcript.md)
>
> `POST /v1/projects/{projectId}/transcript`
>
> 원본 또는 번역된 프로젝트 대본을 검색합니다.

> [card] [프로젝트 만들기](https://api-docs.voicecheap.ai/docs/ko/api-reference/create-project.md)
>
> `POST /v1/projects`
>
> 동영상 또는 오디오 파일을 업로드하고 번역 없이 전사만 시작합니다.

> [card] [번역 시작](https://api-docs.voicecheap.ai/docs/ko/api-reference/translate.md)
>
> `POST /v1/translate`
>
> 비디오 또는 오디오 파일을 업로드하고 번역 프로젝트를 시작합니다.

> [card] [프로젝트 더빙](https://api-docs.voicecheap.ai/docs/ko/api-reference/dub-project.md)
>
> `POST /v1/projects/{projectId}/dub`
>
> 전사가 완료된 프로젝트를 직접 번역한 SRT로 더빙합니다.

> [card] [번역 상태 가져오기](https://api-docs.voicecheap.ai/docs/ko/api-reference/translation-status.md)
>
> `GET /v1/translate/{projectId}/status`
>
> 번역 프로젝트의 상태를 확인하고 결과를 검색합니다.

> [card] [프로젝트 세부 정보 가져오기](https://api-docs.voicecheap.ai/docs/ko/api-reference/project-details.md)
>
> `GET /v1/projects/{projectId}`
>
> 번역된 버전 기록, 립싱크 기록 및 프로젝트 상태를 검색합니다.

> [card] [프로젝트 삭제](https://api-docs.voicecheap.ai/docs/ko/api-reference/delete-project.md)
>
> `DELETE /v1/translate/{projectId}`
>
> 번역 프로젝트와 해당 자산을 영구적으로 삭제합니다.

## 번역 워크플로우

비디오 번역을 위한 일반적인 워크플로우는 다음과 같습니다:

```mermaid theme={null}
sequenceDiagram
    participant Client as 클라이언트
    participant API
    participant Processing as 처리

    Client->>API: POST /v1/translate (파일 + 옵션)
    API->>Processing: 번역 작업 대기열에 추가
    API-->>Client: 201 (projectId)

    loop 상태 확인
        Client->>API: GET /v1/translate/{projectId}/status
        API-->>Client: status (processing/success/failed)
    end

    Note over Client: 상태가 "success"이면 번역된 동영상 URL 다운로드
```

## 응답 형식

아래의 기존 파일 업로드 및 프로젝트 경로는 엔드포인트별 응답 형식을 유지합니다.

성공 응답의 필드는 엔드포인트마다 다릅니다. 프로젝트 생성과 더빙 시작 요청은 `success`, `message`, `projectId`를 반환합니다. 상태 및 프로젝트 세부 정보 요청은 프로젝트 상태를 반환하고, 전사 요청은 JSON, SRT 또는 VTT를 반환합니다. 정확한 필드는 각 엔드포인트 페이지를 확인하세요.

오류는 `code`와 `message`가 포함된 JSON 객체로 반환되며 `details`가 포함될 수도 있습니다. [오류 코드](https://api-docs.voicecheap.ai/docs/ko/api-reference/errors.md)를 참조하세요.

## HTTP 상태 코드

| 상태 코드 | 설명 |
| - | - |
| 200 | 성공 |
| 201 | 생성됨 - 프로젝트 또는 더빙 작업 시작 |
| 202 | 접수됨 - 요청 ID로 비동기 작업 추적 |
| 400 | 잘못된 요청 - 유효하지 않은 매개변수 |
| 401 | 인증되지 않음 - API 키가 유효하지 않거나 누락됨 |
| 403 | 금지됨 - 권한 또는 크레딧 부족 |
| 404 | 찾을 수 없음 - 리소스가 존재하지 않음 |
| 409 | 충돌 - 프로젝트 상태에서 요청을 수행할 수 없음 |
| 413 | 파일 크기 초과 - 업로드한 파일이 한도를 초과함 |
| 429 | 너무 많은 요청 - 속도 제한 초과 |
| 500 | 내부 서버 오류 |
| 502 | 처리 오류 - 전사를 완료할 수 없음 |
| 503 | 일시적으로 서비스 이용 불가 - 같은 요청 ID를 유지하고 재시도 전에 상태 확인 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.