> ## 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는 REST 원칙을 기반으로 구성되어 있습니다. 표준 HTTP 메서드를 사용하고, JSON으로 인코딩된 응답을 반환하며, 표준 HTTP 응답 코드를 사용합니다.

## 기본 URL

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

```
https://api.voicecheap.ai
```

## 인증

모든 요청에는 `x-api-key` 헤더에 전달되는 API 키가 필요합니다. 자세한 내용은 [인증](/docs/ko/authentication) 페이지를 참조하십시오.

## 콘텐츠 유형

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

## 사용 가능한 엔드포인트

<CardGroup cols={2}>
  <Card title="미디어 전사" icon="captions" href="/docs/ko/api-reference/transcribe">
    `POST /v1/transcribe`

    업로드된 파일을 JSON, SRT 또는 VTT로 전사합니다.
  </Card>

  <Card title="프로젝트 대본 내보내기" icon="file-lines" href="/docs/ko/api-reference/project-transcript">
    `POST /v1/projects/{projectId}/transcript`

    원본 또는 번역된 프로젝트 대본을 검색합니다.
  </Card>

  <Card title="번역 시작" icon="play" href="/docs/ko/api-reference/translate">
    `POST /v1/translate`

    비디오 또는 오디오 파일을 업로드하고 번역 프로젝트를 시작합니다.
  </Card>

  <Card title="번역 상태 가져오기" icon="magnifying-glass" href="/docs/ko/api-reference/translation-status">
    `GET /v1/translate/{projectId}/status`

    번역 프로젝트의 상태를 확인하고 결과를 검색합니다.
  </Card>

  <Card title="프로젝트 세부 정보 가져오기" icon="list-tree" href="/docs/ko/api-reference/project-details">
    `GET /v1/projects/{projectId}`

    번역된 버전 기록, 립싱크 기록 및 프로젝트 상태를 검색합니다.
  </Card>

  <Card title="프로젝트 삭제" icon="trash" href="/docs/ko/api-reference/delete-project">
    `DELETE /v1/translate/{projectId}`

    번역 프로젝트와 해당 자산을 영구적으로 삭제합니다.
  </Card>
</CardGroup>

## 번역 워크플로우

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

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Processing

    Client->>API: POST /v1/translate (file + options)
    API->>Processing: Queue translation job
    API-->>Client: 200 OK (projectId)

    loop Poll for status
        Client->>API: GET /v1/translate/{projectId}/status
        API-->>Client: Status (processing/success/failed)
    end

    Note over Client: Download translated video URL when status is "success"
```

## 응답 형식

모든 성공적인 응답은 다음 일반 구조를 따릅니다:

```json theme={null}
{
  "success": true,
  "message": "Description of the result"
  // Additional fields specific to the endpoint
}
```

오류 응답은 다음 구조를 따릅니다:

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}
```

## HTTP 상태 코드

| 상태 코드 | 설명                            |
| ----- | ----------------------------- |
| 200   | 성공                            |
| 400   | 잘못된 요청 - 유효하지 않은 매개변수         |
| 401   | 인증되지 않음 - API 키가 유효하지 않거나 누락됨 |
| 403   | 금지됨 - 권한 또는 크레딧 부족            |
| 404   | 찾을 수 없음 - 리소스가 존재하지 않음        |
| 429   | 너무 많은 요청 - 속도 제한 초과           |
| 500   | 내부 서버 오류                      |