> ## 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.
# 获取或导出项目转写文本
> 以 JSON、SRT 或 VTT 格式获取原文或译文转写文本，可选择包含说话人标签。
以 JSON、SRT 或 VTT 格式获取原文或译文转写文本，可选择包含说话人标签。
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/transcripts_get
```
## 身份验证和权限
在此请求头中发送 VoiceCheap API 密钥。也支持通过 Authorization: Bearer 发送同一 API 密钥。OAuth 访问令牌仅适用于 MCP，此 REST 端点不接受 OAuth
访问令牌。
所需权限: `transcription:read`.
需要有效的付费订阅。权限不会改变团队角色、资源归属、媒体额度或套餐限制。
## 参数
文本值。
最小长度: 1. 最大长度: 200. 匹配模式: `^[^/\\]+$`.
文本值。
允许的值: "original", "translated". 默认值: "original".
文本值。
允许的值: "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".
文本值。
允许的值: "json", "srt", "vtt". 默认值: "json".
布尔值。
默认值: false.
以下 JSON Schema 保留了发现接口公开的确切字段名、嵌套类型、默认值、范围和可接受值。其他跨字段规则列于操作说明中。
```json theme={null}
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"source": {
"default": "original",
"type": "string",
"enum": ["original", "translated"]
},
"targetLanguage": {
"type": "string",
"enum": [
"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"
]
},
"outputFormat": {
"default": "json",
"type": "string",
"enum": ["json", "srt", "vtt"]
},
"includeSpeakerLabels": {
"default": false,
"type": "boolean"
}
},
"required": ["projectId"],
"additionalProperties": false
}
```
## 请求示例
请将示例资源标识符和媒体键替换为账户返回的值。重试同一次修改操作时，请保持请求标识符不变。
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/transcripts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","source":"original","outputFormat":"json","includeSpeakerLabels":false}'
```
```javascript JavaScript theme={null}
const input = {
projectId: 'project_launch_2026',
source: 'original',
outputFormat: 'json',
includeSpeakerLabels: false,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/transcripts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/transcripts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "source": "original", "outputFormat": "json", "includeSpeakerLabels": False},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## 响应
首次执行成功时返回 HTTP 200，操作结果位于 data 下。重放请求时可能改为返回已保存的请求状态。示例展示了一种支持的响应，并未包含所有可选字段。
返回格式化的转写文本对象。JSON 包含 format、transcript 和 contentType；SRT/VTT 还包含 content 和 fileExtension。
```json HTTP 200 theme={null}
{
"data": {
"format": "json",
"transcript": {
"source": "original",
"language": "fr",
"duration": 75,
"text": "Bienvenue au lancement.",
"speakers": [
{
"id": 0,
"label": "Speaker 1"
}
],
"segments": [
{
"index": 0,
"text": "Bienvenue au lancement.",
"begin": 0,
"end": 2,
"duration": 2,
"speaker": 0,
"language": "fr"
}
]
},
"contentType": "application/json"
}
}
```
## 结果字段
| 字段 | 说明 |
| - | - |
| `data.format` | json、srt 或 vtt。 |
| `data.contentType` | application/json、application/x-subrip; charset=utf-8 或 text/vtt; charset=utf-8。 |
| `data.content` | 仅用于 srt/vtt 的字幕文本。 |
| `data.fileExtension` | 仅用于文本导出的 srt 或 vtt。 |
| `data.transcript.source` | original 或 translated。 |
| `data.transcript.language` | 转写文本的语言。 |
| `data.transcript.duration` | 已存储媒体时长与最后片段结束时间两者中的较大值，单位为秒。 |
| `data.transcript.text` | 拼接后的非空片段文本。 |
| `data.transcript.speakers` | 按数字 id 排序的不重复说话人，包含生成的 Speaker N 标签。 |
| `data.transcript.segments` | 按 begin 和 index 排序的规范化片段，包含 index、text、begin、end、duration、speaker、language，以及可选的 confidence、finalSpeedFactor、words。 |
| `data.transcript.workId` | 翻译后的转写文本包含此字段。 |
| `data.transcript.targetLanguage` | 翻译后的转写文本包含此字段。 |
| `data.transcript.segments[].begin` | 开始时间，单位为秒，规范化为三位小数。 |
| `data.transcript.segments[].end` | 结束时间，单位为秒，规范化为三位小数。 |
| `data.transcript.segments[].duration` | 以秒为单位的正数片段时长。 |
| `data.transcript.segments[].speaker` | 从零开始的说话人编号。 |
| `data.transcript.segments[].finalSpeedFactor` | 可选的翻译语音时长与其片段时间窗口的比值，四舍五入为三位小数；大于 1 表示语音需要加速。 |
## outputFormat srt；source translated，targetLanguage english，includeSpeakerLabels true。
返回带说话人前缀的翻译转写文本和 SRT 内容。
```json HTTP 200 theme={null}
{
"data": {
"format": "srt",
"transcript": {
"source": "translated",
"language": "english",
"duration": 75,
"text": "Welcome to the product launch.",
"speakers": [
{
"id": 0,
"label": "Speaker 1"
}
],
"segments": [
{
"index": 0,
"text": "Welcome to the product launch.",
"begin": 0,
"end": 2,
"duration": 2,
"speaker": 0,
"language": "english",
"finalSpeedFactor": 1.08
}
],
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"targetLanguage": "english"
},
"content": "1\n00:00:00,000 --> 00:00:02,000\nSpeaker 1: Welcome to the product launch.\n",
"contentType": "application/x-subrip; charset=utf-8",
"fileExtension": "srt"
}
}
```
## outputFormat 为 vtt；source 为 translated，targetLanguage 为 english，includeSpeakerLabels 为 true。
返回带音色标签的翻译后转写文本和 WEBVTT 内容。
```json HTTP 200 theme={null}
{
"data": {
"format": "vtt",
"transcript": {
"source": "translated",
"language": "english",
"duration": 75,
"text": "Welcome to the product launch.",
"speakers": [
{
"id": 0,
"label": "Speaker 1"
}
],
"segments": [
{
"index": 0,
"text": "Welcome to the product launch.",
"begin": 0,
"end": 2,
"duration": 2,
"speaker": 0,
"language": "english",
"finalSpeedFactor": 1.08
}
],
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"targetLanguage": "english"
},
"content": "WEBVTT\n\n1\n00:00:00.000 --> 00:00:02.000\nWelcome to the product launch.\n",
"contentType": "text/vtt; charset=utf-8",
"fileExtension": "vtt"
}
}
```
## 操作说明
* source 默认为 original，outputFormat 默认为 json，includeSpeakerLabels 默认为 false。使用翻译后的源内容时必须提供 targetLanguage。
* 对于翻译后的转写文本，会选择与 targetLanguage 匹配的最新语言内容。此操作没有 workId 或 translatedVersionId 输入。
* SRT 和 VTT 导出仍是 JSON 操作结果：content 包含字幕文本，同一对象中仍可获取 transcript。此处理程序不返回可直接下载的原始响应。
* includeSpeakerLabels 仅影响文本导出的字幕条目：SRT 使用 Speaker N: 前缀，VTT 使用 voice 标签。
* 若存在已存储的转写单词数据，会公开 index、text、speaker 和可选的 confidence；不会凭空添加单词级时间戳。存在生成语音的时序数据时，翻译片段可能会公开 finalSpeedFactor。
## 用量
每次成功调用消耗一次月度 API/MCP 调用额度。媒体额度和操作本身的生成限额也适用。
## 错误
| HTTP 状态 | 代码 | 含义或恢复方式 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | 凭证通过 access\_token 或 api\_key 查询参数提供。请在标头中发送凭证。 |
| 400 | `VALIDATION_ERROR` | 请根据架构更正输入。无效或不一致的值会在执行前被拒绝。 |
| 401 | `API_KEY_EXPIRED` | API 密钥已过期。 |
| 401 | `INVALID_API_KEY` | 请提供有效且未过期的 API 密钥。 |
| 401 | `INVALID_CREDENTIAL` | Authorization 标头格式错误或与 x-api-key 冲突。 |
| 401 | `MISSING_CREDENTIAL` | 未提供可用的请求头凭据，或其长度超过 4096 个字符。 |
| 401 | `USER_NOT_FOUND` | 该凭据对应的账户已不存在。 |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | 此凭据对应的用户属于多个团队，因此计费上下文不明确。 |
| 403 | `FORBIDDEN` | 通过身份验证的调用者无权访问此项目。 |
| 403 | `INSUFFICIENT_SCOPE` | 请授予全部所需权限，或选择其他凭据。 |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | 无法验证该账户的集成限制。 |
| 403 | `SUBSCRIPTION_REQUIRED` | 请使用有效的付费订阅。 |
| 403 | `TEAM_OWNER_NOT_FOUND` | 找不到实际生效的团队所有者账户。 |
| 404 | `PROJECT_NOT_FOUND` | 可访问的账户中不存在此项目。 |
| 404 | `TRANSCRIPT_NOT_FOUND` | 所请求的源和目标语言没有可用的转写文本。 |
| 409 | `TRANSCRIPT_NOT_READY` | 所请求的原始或翻译转写文本仍在处理中。 |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 请等待月度额度重置，或更改套餐。 |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | 如果提供了 Retry-After，请等待其指定的时间，并采用退避重试。 |
| 500 | `INTERNAL_ERROR` | 在决定是否重试修改操作前，请检查已保存的请求状态和资源历史记录。 |
| 503 | `SERVER_RESTARTING` | 服务器正在重启。请稍后重试；对于修改操作，请保持请求标识符不变。 |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["transcription:read"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.