> ## 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/zh/api-reference/actions.md)。这些工作流也可通过[账户 MCP 服务器](https://api-docs.voicecheap.ai/docs/zh/ai/model-context-protocol.md)使用，但 Webhook 签名密钥的创建和轮换需要使用 REST。在[集成](https://api-docs.voicecheap.ai/docs/zh/ai/integrations.md)中管理凭据，并查看[使用限制](https://api-docs.voicecheap.ai/docs/zh/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/zh/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/zh/api-reference/actions/requests/action-request-get.md)以获取结果。操作请求完成后，媒体任务仍可能继续运行。

浏览[按领域分类的全部操作](https://api-docs.voicecheap.ai/docs/zh/api-reference/actions.md)，或[查看密钥获准使用的操作和结构定义](https://api-docs.voicecheap.ai/docs/zh/api-reference/discovery/actions-list.md)。每个页面均列出权限、参数、示例和错误。

## 内容类型

* **请求**：文件上传使用 `multipart/form-data`，其他请求使用 `application/json`
* **响应**：JSON 端点返回 `application/json`。转录导出也可以返回 SRT 或 VTT 文本。

## 文件上传和现有项目路由

> [card] [转录媒体](https://api-docs.voicecheap.ai/docs/zh/api-reference/transcribe.md)
>
> `POST /v1/transcribe`
>
> 将上传的文件转录为 JSON、SRT 或 VTT 格式。

> [card] [导出项目转录](https://api-docs.voicecheap.ai/docs/zh/api-reference/project-transcript.md)
>
> `POST /v1/projects/{projectId}/transcript`
>
> 检索原始或翻译后的项目转录。

> [card] [创建项目](https://api-docs.voicecheap.ai/docs/zh/api-reference/create-project.md)
>
> `POST /v1/projects`
>
> 上传视频或音频文件，仅启动转录。

> [card] [开始翻译](https://api-docs.voicecheap.ai/docs/zh/api-reference/translate.md)
>
> `POST /v1/translate`
>
> 上传视频或音频文件并启动翻译项目。

> [card] [为项目配音](https://api-docs.voicecheap.ai/docs/zh/api-reference/dub-project.md)
>
> `POST /v1/projects/{projectId}/dub`
>
> 使用您自己的译文 SRT，为已转录的项目配音。

> [card] [获取翻译状态](https://api-docs.voicecheap.ai/docs/zh/api-reference/translation-status.md)
>
> `GET /v1/translate/{projectId}/status`
>
> 检查翻译项目的状态并检索结果。

> [card] [获取项目详情](https://api-docs.voicecheap.ai/docs/zh/api-reference/project-details.md)
>
> `GET /v1/projects/{projectId}`
>
> 检索翻译版本历史、口型同步历史和项目状态。

> [card] [删除项目](https://api-docs.voicecheap.ai/docs/zh/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/zh/api-reference/errors.md)。

## HTTP 状态代码

| 状态代码 | 描述 |
| - | - |
| 200 | 成功 |
| 201 | 已创建 - 项目或配音任务已启动 |
| 202 | 已接受 - 使用请求标识符跟踪异步操作 |
| 400 | 错误的请求 - 无效的参数 |
| 401 | 未授权 - API 密钥无效或缺失 |
| 403 | 禁止访问 - 权限或额度不足 |
| 404 | 未找到 - 资源不存在 |
| 409 | 冲突 - 项目状态不允许此请求 |
| 413 | 文件过大 - 上传文件超出限制 |
| 429 | 请求过多 - 超出速率限制 |
| 500 | 内部服务器错误 |
| 502 | 处理错误 - 转录未能完成 |
| 503 | 服务暂时不可用 - 保留相同请求标识符，并在重试前检查状态 |


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