> ## 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 应用中打开该项目以触发翻译，或使用 [获取项目详情](https://api-docs.voicecheap.ai/docs/zh/api-reference/project-details.md) 检查项目状态。

## 并发限制

创建项目、翻译和配音都会检查账户的进行中翻译上限（最多 10 个，实际限制可能更低）。只有进行中的翻译或配音任务占用名额；仅转录的项目不占用。达到上限时，API 返回 `CONCURRENT_TRANSLATION_LIMIT_REACHED`（HTTP 429）。实际限制见 `details.limit`。

## 请求

此端点接受带有文件上传的 `multipart/form-data`。

### 标头

**x-api-key** `string` *required*

您的 VoiceCheap API 密钥。从 [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api) 获取一个。

### 正文参数

**file** `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。

**targetLanguage** `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`、`pt_brazil`、`punjabi`、`romanian`、`russian`、`serbian`、`slovak`、`slovenian`、`spanish`、`swahili`、`swedish`、`tagalog`、`tamil`、`telugu`、`thai`、`turkish`、`ukrainian`、`urdu`、`vietnamese`、`welsh`、`yoruba`、`zulu`

**originalLanguage** `string`

使用 ISO 语言代码的内容源语言（例如 `en`、`es`、`fr`、`de`、`ja`、`zh`）。

> [!WARNING]
>
> **强烈建议：留空以进行自动检测。**
>
> 仅在您 100% 确定语言代码正确且为有效 ISO 格式时才提供此参数。错误的语言代码会导致转录失败。我们的自动检测支持 80 多种语言，且非常准确。

**默认值：** `auto-detect`

**projectName** `string`

项目的自定义名称。有助于在您的仪表板中识别项目。

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

**webhookUrl** `string`

一个接收此项目 [webhook 事件](https://api-docs.voicecheap.ai/docs/zh/api-reference/webhooks.md) 的 https 端点，
覆盖您账户上配置的端点。

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

**numberOfSpeakers** `string`

`auto-detect` 或从 `1` 到 `32` 的整数。提供已知的说话人数量可以改善说话人日志记录。

**默认值：** `auto-detect`

**brandVocabulary** `string`

一个包含特定于请求的名称、品牌、首字母缩略词或专业术语的 JSON 字符串数组。这些术语将与保存的账户或团队词汇表合并。

```json theme={null}
["VoiceCheap", "SmartSync", "ITC Global"]
```

**removeFillerWords** `boolean`

在转录过程中删除常见的填充词。

**默认值：** `true`

**sourceSrt** `string`

现有的源语言 SRT 转录。提供时，`originalLanguage` 必须是明确的语言代码，而不是 `auto-detect`。

此端点仅用于项目创建 + 转录启动。字幕、语音克隆和背景音乐等翻译选项由 `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 | `SUBSCRIPTION_REQUIRED` | API 访问需要 Starter 或更高级别的计划 |
| 429 | `RATE_LIMIT_EXCEEDED` | 请求过多（限制：每分钟 10 次请求） |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | 已达到账户并发翻译上限；参见 `details.limit` |
| 500 | `INTERNAL_ERROR` | 意外的服务器错误 |


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