> ## 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 앱에서 프로젝트를 열어 번역을 트리거하거나 [프로젝트 세부 정보 가져오기](/docs/ko/api-reference/project-details)을(를) 사용하여 프로젝트 상태를 검사할 수 있습니다.

## 동시성 제한

이 엔드포인트는 `POST /v1/translate`과(와) 동일한 동시성 제한을 공유합니다(계정당 최대 10개의 진행 중인 번역). 제한에 도달하면 요청은 `CONCURRENT_TRANSLATION_LIMIT_REACHED`(HTTP 429)을(를) 반환합니다.

## 요청

이 엔드포인트는 파일 업로드와 함께 `multipart/form-data`을(를) 허용합니다.

### 헤더

<ParamField header="x-api-key" type="string" required>
  귀하의 VoiceCheap API 키입니다. [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api)에서 키를 받으십시오.
</ParamField>

### 본문 매개변수

<ParamField body="file" type="file" required>
  업로드할 비디오 또는 오디오 파일입니다.

  **지원되는 비디오 형식:** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg`

  **지원되는 오디오 형식:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm`

  **플랜별 최대 파일 크기:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB 및 Enterprise 60 GB.
</ParamField>

<ParamField body="targetLanguage" type="string" required>
  이 프로젝트와 연결할 대상 언어입니다. 소문자여야 합니다.

  **허용된 값(70개 이상):** `afrikaans`, `albanian`, `amharic`, `arabic`, `armenian`, `assamese`, `azerbaijani`, `basque`, `belarusian`, `bengali`, `bosnian`, `bulgarian`, `catalan`, `croatian`, `czech`, `danish`, `dutch`, `english`, `british english`, `estonian`, `finnish`, `french`, `french canadian`, `galician`, `german`, `greek`, `gujarati`, `hebrew`, `hindi`, `hungarian`, `icelandic`, `indonesian`, `irish`, `italian`, `japanese`, `kannada`, `kazakh`, `khmer`, `korean`, `lao`, `latvian`, `lithuanian`, `macedonian`, `malay`, `malayalam`, `mandarin`, `marathi`, `mongolian`, `nepali`, `norwegian`, `persian`, `polish`, `portuguese`, `brazilian portuguese`, `punjabi`, `romanian`, `russian`, `serbian`, `slovak`, `slovenian`, `spanish`, `swahili`, `swedish`, `tagalog`, `tamil`, `telugu`, `thai`, `turkish`, `ukrainian`, `urdu`, `vietnamese`, `welsh`, `yoruba`, `zulu`
</ParamField>

<ParamField body="originalLanguage" type="string">
  ISO 언어 코드를 사용하는 콘텐츠의 원본 언어입니다(예: `en`, `es`, `fr`, `de`, `ja`, `zh`).

  <Warning>
    **강력 권장: 자동 감지를 위해 이 항목을 비워 두십시오.**

    언어 코드가 정확하고 유효한 ISO 형식임을 100% 확신하는 경우에만 이 매개변수를 제공하십시오. 잘못된 언어 코드는 전사 실패를 유발합니다. 당사의 자동 감지는 80개 이상의 언어를 지원하며 매우 정확합니다.
  </Warning>

  **기본값:** `auto-detect`
</ParamField>

<ParamField body="projectName" type="string">
  프로젝트의 사용자 지정 이름입니다. 대시보드에서 프로젝트를 식별하는 데 유용합니다.

  **기본값:** 제공되지 않으면 프로젝트 ID가 사용됩니다.
</ParamField>

<ParamField body="webhookUrl" type="string">
  이 프로젝트에 대한 [웹훅 이벤트](/docs/ko/api-reference/webhooks)을(를) 수신하는 https 엔드포인트이며,
  계정에 구성된 엔드포인트를 재정의합니다.

  **기본값:** 구성된 경우 계정 웹훅 엔드포인트.
</ParamField>

<ParamField body="numberOfSpeakers" type="string">
  `auto-detect` 또는 `1`에서 `32` 사이의 정수입니다. 알려진 화자 수를 제공하면 화자 분리(diarization)가 향상될 수 있습니다.

  **기본값:** `auto-detect`
</ParamField>

<ParamField body="brandVocabulary" type="string">
  요청별 이름, 브랜드, 약어 또는 전문 용어의 JSON 문자열 배열입니다. 이러한 용어는 저장된 계정 또는 팀 용어집과 병합됩니다.

  ```json theme={null}
  ["VoiceCheap", "SmartSync", "ITC Global"]
  ```
</ParamField>

<ParamField body="removeFillerWords" type="boolean">
  전사 중에 일반적인 채움 단어를 제거합니다.

  **기본값:** `true`
</ParamField>

<ParamField body="sourceSrt" type="string">
  기존 원본 언어 SRT 전사본입니다. 제공되는 경우 `originalLanguage`은(는) `auto-detect`이(가) 아닌 명시적인 언어 코드여야 합니다.
</ParamField>

이 엔드포인트는 프로젝트 생성 + 전사 시작 전용입니다. 자막, 음성 복제, 음성 분리 및 배경 오디오와 같은 번역 옵션은 `POST /v1/translate`에서 처리합니다.

## 요청 예시

```bash theme={null}
curl -X POST "https://api.voicecheap.ai/v1/projects" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/video.mp4" \
  -F "targetLanguage=french" \
  -F "projectName=Launch Demo" \
  -F "numberOfSpeakers=2" \
  -F 'brandVocabulary=["VoiceCheap","SmartSync"]' \
  -F "removeFillerWords=true"
```

## 응답 예시

```json theme={null}
{
  "success": true,
  "message": "Project created. Transcription started.",
  "projectId": "project_123",
  "projectName": "Launch Demo",
  "targetLanguage": "french",
  "status": "processing"
}
```

## 오류

| 상태  | 코드                                     | 설명                                       |
| --- | -------------------------------------- | ---------------------------------------- |
| 400 | `FILE_REQUIRED`                        | 요청과 함께 업로드된 파일이 없습니다                     |
| 400 | `INVALID_FILE_TYPE`                    | 지원되지 않는 파일 형식입니다                         |
| 400 | `DURATION_DETECTION_FAILED`            | 업로드된 파일의 길이를 감지할 수 없습니다                  |
| 400 | `INVALID_MULTIPART_REQUEST`            | 멀티파트 폼 데이터가 잘못되었거나 필드 제한을 초과했습니다         |
| 400 | `INVALID_BRAND_VOCABULARY`             | 요청별 용어집 항목이 유효하지 않습니다                    |
| 400 | `INVALID_SOURCE_SRT`                   | 제공된 소스 SRT가 잘못되었습니다                      |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT`     | sourceSrt에는 명시적인 originalLanguage가 필요합니다 |
| 400 | `VIDEO_TOO_LONG`                       | 미디어 길이가 사용자의 플랜 제한을 초과합니다                |
| 413 | `FILE_TOO_LARGE`                       | 업로드된 파일이 사용자의 플랜 제한을 초과합니다               |
| 401 | `MISSING_API_KEY`                      | API 키가 필요합니다                             |
| 401 | `INVALID_API_KEY_FORMAT`               | API 키는 `vc_`으로 시작해야 합니다                  |
| 401 | `INVALID_API_KEY`                      | 제공된 API 키가 유효하지 않습니다                     |
| 403 | `API_ACCESS_REQUIRED`                  | 이 계정에는 API 액세스가 필요합니다                    |
| 403 | `SUBSCRIPTION_REQUIRED`                | API 액세스에는 유료 구독이 필요합니다                   |
| 429 | `RATE_LIMIT_EXCEEDED`                  | 요청이 너무 많습니다 (제한: 분당 10회 요청)              |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | 진행 중인 번역이 너무 많습니다 (제한: 동시 번역 10개)        |
| 500 | `INTERNAL_ERROR`                       | 예기치 않은 서버 오류                             |