> ## 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/zh/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>
    **强烈建议：留空以进行自动检测。**

    仅在您 100% 确定语言代码正确且为有效 ISO 格式时才提供此参数。错误的语言代码会导致转录失败。我们的自动检测支持 80 多种语言，且非常准确。
  </Warning>

  **默认值：** `auto-detect`
</ParamField>

<ParamField body="projectName" type="string">
  项目的自定义名称。有助于在您的仪表板中识别项目。

  **默认值：** 如果未提供，将使用项目 ID。
</ParamField>

<ParamField body="webhookUrl" type="string">
  一个接收此项目 [webhook 事件](/docs/zh/api-reference/webhooks) 的 https 端点，
  覆盖您账户上配置的端点。

  **默认值：** 配置账户 webhook 端点时，使用该端点。
</ParamField>

<ParamField body="numberOfSpeakers" type="string">
  `auto-detect` 或从 `1` 到 `32` 的整数。提供已知的说话人数量可以改善说话人日志记录。

  **默认值：** `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`                       | 意外的服务器错误                         |