> ## 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/zh/authentication) 页面。

## 内容类型

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

## 可用端点

<CardGroup cols={2}>
  <Card title="转录媒体" icon="captions" href="/docs/zh/api-reference/transcribe">
    `POST /v1/transcribe`

    将上传的文件转录为 JSON、SRT 或 VTT 格式。
  </Card>

  <Card title="导出项目转录" icon="file-lines" href="/docs/zh/api-reference/project-transcript">
    `POST /v1/projects/{projectId}/transcript`

    检索原始或翻译后的项目转录。
  </Card>

  <Card title="开始翻译" icon="play" href="/docs/zh/api-reference/translate">
    `POST /v1/translate`

    上传视频或音频文件并启动翻译项目。
  </Card>

  <Card title="获取翻译状态" icon="magnifying-glass" href="/docs/zh/api-reference/translation-status">
    `GET /v1/translate/{projectId}/status`

    检查翻译项目的状态并检索结果。
  </Card>

  <Card title="获取项目详情" icon="list-tree" href="/docs/zh/api-reference/project-details">
    `GET /v1/projects/{projectId}`

    检索翻译版本历史、口型同步历史和项目状态。
  </Card>

  <Card title="删除项目" icon="trash" href="/docs/zh/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  | 内部服务器错误           |