概览
音频和视频
支持网站当前全部转录格式。
异步任务
请求会立即返回任务 ID。每个账户最多可有 50 个活动任务,由后台队列异步处理。
US$0.04 / hour
按向上取整后的分钟扣积分。
身份验证
所有请求都需要在 Authorization 请求头中使用 Bearer API Key。密钥只在生成时完整显示一次。
HTTP header
Authorization: Bearer sz_live_your_api_key快速开始:提交远程文件
文件地址必须可由服务器通过 HTTPS 直接下载,不能要求登录或 Cookie。POST 会立即返回 202,转录在后台异步执行。网络重试时请重复使用同一个 Idempotency-Key,避免创建重复任务。
cURL
curl -X POST https://scribezip.com/api/v1/transcriptions \
-H "Authorization: Bearer $SCRIBEZIP_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/meeting.mp3",
"language": "auto",
"accuracy_mode": "balanced"
}'分片上传本地文件
- 提交文件名、字节大小和 MIME 类型,创建上传会话。
- 按返回的 part_size 顺序上传全部分片。
- 调用 complete_url 开始处理。
Node.js 22+
import { open, stat } from "node:fs/promises";
const apiKey = process.env.SCRIBEZIP_API_KEY;
const path = "./meeting.mp3";
const file = await stat(path);
const idempotencyKey = crypto.randomUUID();
async function requestJson(url, init) {
const response = await fetch(url, init);
const body = await response.json().catch(() => null);
if (!response.ok) {
throw new Error(body?.error?.message ?? `HTTP ${response.status}`);
}
return body;
}
const created = await requestJson("https://scribezip.com/api/v1/transcriptions", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
},
body: JSON.stringify({
file_name: "meeting.mp3",
file_size: file.size,
mime_type: "audio/mpeg",
language: "auto",
}),
});
const handle = await open(path, "r");
const { part_size, part_count, part_url, complete_url } = created.upload;
for (let part = 1; part <= part_count; part += 1) {
const length = Math.min(part_size, file.size - (part - 1) * part_size);
const buffer = Buffer.alloc(length);
await handle.read(buffer, 0, length, (part - 1) * part_size);
await requestJson(`${part_url}?part_number=${part}`, {
method: "PUT",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Length": String(length),
},
body: buffer,
});
}
await handle.close();
const job = await requestJson(complete_url, {
method: "POST",
headers: { Authorization: `Bearer ${apiKey}` },
});
console.log(job.data.id);如果网络中断,可以使用相同的 Idempotency-Key 重试创建请求,也可以用相同的 part_number 重传分片或再次调用 complete_url。
接口参考
接口与成功状态码
| HTTP | Endpoint | Status | 用途 |
|---|---|---|---|
| POST | /api/v1/transcriptions | 202 | 提交远程 HTTPS 文件 |
| POST | /api/v1/transcriptions | 201 | 创建本地文件上传会话 |
| PUT | /api/v1/transcriptions/{id}/upload?part_number=N | 200 | 上传一个文件分片 |
| POST | /api/v1/transcriptions/{id}/complete | 202 / 200 | 开始处理;已完成任务的重复请求返回 200 |
| GET | /api/v1/transcriptions/{id} | 200 | 查询单个任务与结果 |
| GET | /api/v1/transcriptions | 200 | 获取最近 100 条 API 记录 |
| DELETE | /api/v1/transcriptions/{id} | 200 | 取消任务或删除结果 |
创建任务参数
| 名称 | 位置/类型 | 必填 | 说明 |
|---|---|---|---|
| url | JSON / string | 是(远程) | 服务器可直接下载的 HTTPS 地址 |
| file_name | JSON / string | 是(本地) | 包含扩展名的文件名 |
| file_size | JSON / integer | 是(本地) | 文件的精确字节数 |
| mime_type | JSON / string | 否 | 文件的 MIME 类型;默认 application/octet-stream |
| language | JSON / string | 否 | 默认 auto |
| accuracy_mode | JSON / string | 否 | fast、balanced(默认)或 accurate |
| translate_to_english | JSON / boolean | 否 | 设为 true 时翻译为英文 |
| Idempotency-Key | Header / string | 否,强烈建议 | 1–128 位,仅限字母、数字、点、下划线、冒号和连字符 |
相同 Idempotency-Key 与相同参数会返回原任务(HTTP 200,并带 Idempotency-Replayed: true);相同键配合不同参数会返回 409 idempotency_conflict。
常用响应头
Location— 新任务的查询地址。Retry-After— 再次轮询或重试前应等待的秒数。Idempotency-Replayed: true— 返回的是已有任务,没有新建重复任务。
查询任务与结果
请优先按照 Retry-After 响应头轮询(通常为 3 秒)。状态可能为 accepted、uploading、inspecting、preprocessing、queued、processing、merging、completed、failed 或 deleted。一个账户最多可有 50 个活动任务。
cURL
curl https://scribezip.com/api/v1/transcriptions/REQUEST_ID \
-H "Authorization: Bearer $SCRIBEZIP_API_KEY"Node.js 22+ polling
const apiKey = process.env.SCRIBEZIP_API_KEY;
const requestId = "REQUEST_ID";
const terminalStatuses = new Set(["completed", "failed", "deleted"]);
while (true) {
const response = await fetch(
`https://scribezip.com/api/v1/transcriptions/${requestId}`,
{ headers: { Authorization: `Bearer ${apiKey}` } },
);
const body = await response.json();
if (!response.ok) {
throw new Error(body.error?.message ?? `HTTP ${response.status}`);
}
if (terminalStatuses.has(body.data.status)) {
console.log(body.data);
break;
}
const retryAfter = Number(response.headers.get("retry-after") ?? 3);
await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
}200 response
{
"data": {
"id": "request_id",
"status": "completed",
"progress": 100,
"file_name": "meeting.mp3",
"source_kind": "audio",
"duration_seconds": 330,
"billed_minutes": 6,
"credits_charged": 6,
"transcript": {
"text": "Welcome to the meeting…",
"segments": [
{ "start": 0, "end": 2.4, "text": "Welcome to the meeting…" }
]
},
"error": null
},
"meta": { "balance_credits": 14994 }
}DELETE /api/v1/transcriptions/REQUEST_ID 可以取消活动任务,或删除已完成的结果和仍保留的媒体。未完成任务如已扣积分会自动退回;删除已完成任务不会退款。
计费规则
| 价格 | US$0.04 / 转录小时 |
|---|---|
| 积分单位 | 1 积分 = 1 个计费分钟 |
| 取整 | 不足 1 分钟按 1 分钟;5:30 按 6 分钟 |
| 充值 | US$10 / $20 / $50 / $100 |
| 首次充值退款 | 首次 API 充值后 7 天内可联系支持申请退款;只按原购买价格比例退还该笔充值尚未使用的部分 |
| 失败或取消 | 未完成任务已扣的积分自动退回;已完成任务删除后不退款 |
数据保存
API 使用历史只保存 30 天。
实际上传的视频源文件会在处理后删除。
直接上传或从视频提取的音频最多保存 60 天,除非用户提前删除。
API Key 只保存不可逆哈希,完整密钥无法再次查看。
常见错误码
| HTTP | Code | 说明 |
|---|---|---|
400 | invalid_json / invalid_idempotency_key / empty_upload | 请求正文、幂等键格式或上传内容不正确 |
400 | invalid_part / part_size_mismatch / invalid_parts | 分片编号、大小或完整性不正确 |
400 | invalid_remote_url / insecure_remote_url / remote_host_blocked | 远程地址无效、不安全或被禁止访问 |
401 | invalid_api_key | 密钥无效或已撤销 |
402 | insufficient_credits | API 积分不足 |
404 | not_found | 任务或上传会话不存在 |
409 | idempotency_pending / idempotency_conflict | 原请求仍在写入,或同一个键被用于不同参数 |
409 | invalid_status / upload_session_missing / upload_incomplete | 当前任务状态或上传会话不允许此操作 |
410 | upload_expired | 上传会话已过期 |
413 | file_too_large | 文件字节数无效或超过允许大小 |
415 | unsupported_file / invalid_file_signature | 格式不支持,或文件内容与扩展名不符 |
422 | remote_host_unresolved | 远程主机无法解析 |
429 | active_job_limit | 账户已有 50 个活动任务 |
429 | rate_limited | 请求过于频繁 |
500 | request_failed / upload_failed / complete_failed | 请求、分片上传或启动处理失败 |
502 | remote_dns_failed | 暂时无法验证远程主机;可以重试 |
503 | provider_unavailable / queue_unavailable | 转录服务或后台队列暂时不可用;按 Retry-After 重试 |