ScribeZip API

把音频和视频转录接入你的产品

通过一个简单的 REST API 上传媒体或提交远程文件地址,异步获取带时间戳的转录结果。

概览

音频和视频

支持网站当前全部转录格式。

异步任务

请求会立即返回任务 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"
  }'

分片上传本地文件

  1. 提交文件名、字节大小和 MIME 类型,创建上传会话。
  2. 按返回的 part_size 顺序上传全部分片。
  3. 调用 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。

接口参考

接口与成功状态码

HTTPEndpointStatus用途
POST/api/v1/transcriptions202提交远程 HTTPS 文件
POST/api/v1/transcriptions201创建本地文件上传会话
PUT/api/v1/transcriptions/{id}/upload?part_number=N200上传一个文件分片
POST/api/v1/transcriptions/{id}/complete202 / 200开始处理;已完成任务的重复请求返回 200
GET/api/v1/transcriptions/{id}200查询单个任务与结果
GET/api/v1/transcriptions200获取最近 100 条 API 记录
DELETE/api/v1/transcriptions/{id}200取消任务或删除结果

创建任务参数

名称位置/类型必填说明
urlJSON / string是(远程)服务器可直接下载的 HTTPS 地址
file_nameJSON / string是(本地)包含扩展名的文件名
file_sizeJSON / integer是(本地)文件的精确字节数
mime_typeJSON / string文件的 MIME 类型;默认 application/octet-stream
languageJSON / string默认 auto
accuracy_modeJSON / stringfast、balanced(默认)或 accurate
translate_to_englishJSON / boolean设为 true 时翻译为英文
Idempotency-KeyHeader / 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 只保存不可逆哈希,完整密钥无法再次查看。

常见错误码

HTTPCode说明
400invalid_json / invalid_idempotency_key / empty_upload请求正文、幂等键格式或上传内容不正确
400invalid_part / part_size_mismatch / invalid_parts分片编号、大小或完整性不正确
400invalid_remote_url / insecure_remote_url / remote_host_blocked远程地址无效、不安全或被禁止访问
401invalid_api_key密钥无效或已撤销
402insufficient_creditsAPI 积分不足
404not_found任务或上传会话不存在
409idempotency_pending / idempotency_conflict原请求仍在写入,或同一个键被用于不同参数
409invalid_status / upload_session_missing / upload_incomplete当前任务状态或上传会话不允许此操作
410upload_expired上传会话已过期
413file_too_large文件字节数无效或超过允许大小
415unsupported_file / invalid_file_signature格式不支持,或文件内容与扩展名不符
422remote_host_unresolved远程主机无法解析
429active_job_limit账户已有 50 个活动任务
429rate_limited请求过于频繁
500request_failed / upload_failed / complete_failed请求、分片上传或启动处理失败
502remote_dns_failed暂时无法验证远程主机;可以重试
503provider_unavailable / queue_unavailable转录服务或后台队列暂时不可用;按 Retry-After 重试