语音转文字 API

直接在你的代码里把音频和视频变成文字。一个密钥即可获得完整流水线：任意输入格式、自动语言识别（约99种语言）、长文件自动切分，以及 LLM 后处理——整洁文本、摘要、任务清单、翻译。

快速开始

1. 注册并确认邮箱。2. 在账户中打开“API 密钥”并创建密钥（只显示一次）。3. 发送第一个请求：

上传文件并等待结果：

curl -X POST https://oratext.com/api/v1/transcriptions \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -F "file=@meeting.mp3" \
  -F "wait=true"

使用 wait=true 时，服务器会保持连接最长约90秒，并在同一个请求中直接返回完成的文本——足以覆盖大多数文件。较长的录音请使用下方的异步流程。

身份验证

每个请求都必须携带请求头 Authorization: Bearer ora_sk_… 。密钥在账户中创建，可随时撤销。请务必保密：任何拿到密钥的人都会消耗你的分钟数。

Authorization: Bearer ora_sk_YOUR_KEY

创建转写任务

POST /api/v1/transcriptions

POST /api/v1/transcriptions 接受带文件的 multipart/form-data，或带 url 参数的 JSON/表单——文件由我们代为下载（公网主机，端口80/443，最多3次重定向）。每个请求只能指定一个来源。

参数	说明
`file`	音频或视频文件（multipart/form-data）。支持 MP3、WAV、M4A、OGG、MP4、MOV 等绝大多数格式。
`url`	指向文件的 http(s) 直链，可代替上传。
`level`	处理级别：standard、premium 或 ultra。默认为你套餐的最高级别。级别越高，模型越强。
`mode`	可选，转写完成后立即执行的后处理：clean（去除口头语）、summary（摘要）、tasks（任务清单）或 translate（翻译）。结果放在 mode_text 字段中，与原文一并返回。
`target_lang`	mode=translate 时的目标语言，例如“English”或“中文”。
`wait`	true：保持请求直到结果就绪（最长约90秒）。若超时会返回 202 和 id，之后照常轮询状态即可。

或传入链接，并顺便生成摘要：

curl -X POST https://oratext.com/api/v1/transcriptions \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/podcast.mp3", "mode": "summary", "wait": "true"}'

成功状态码：201——任务已创建（未用 wait）；200——wait 等到了结果；202——wait 超时，请继续按 id 轮询。

获取结果

GET /api/v1/transcriptions/{id}

每1–3秒轮询一次 GET /api/v1/transcriptions/{id}。状态依次为 queued → processing → done；error 表示处理失败（不会扣分钟数——任务未完成），rejected 表示被业务规则拦截（配额、时长）。

查询状态 / 获取结果：

curl -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  https://oratext.com/api/v1/transcriptions/JOB_ID

完成后的响应：

{
  "id": "3f2b8c1e-5a70-4a3e-9c0f-1d2e3f4a5b6c",
  "status": "done",
  "level": "standard",
  "duration_sec": 184.2,
  "language": "ru",
  "mode": "summary",
  "text": "…full transcript…",
  "mode_text": "…summary…"
}

文本后处理

POST /api/v1/transcriptions/{id}/process

任何已完成的转写都可以再次处理，且不扣分钟数：调用 POST /api/v1/transcriptions/{id}/process，附带 mode，翻译时再加 target_lang。每条转写最多可处理20次。

curl -X POST https://oratext.com/api/v1/transcriptions/JOB_ID/process \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "translate", "target_lang": "English"}'

查询配额

GET /api/v1/usage

GET /api/v1/usage 返回你的套餐、总额度、已用和剩余分钟数，以及配额重置时间。发送大文件前建议先调用它。

{
  "plan": "free",
  "period": "day",
  "limit_minutes": 5.0,
  "used_minutes": 1.2,
  "remaining_minutes": 3.8,
  "resets_at": "2026-08-06T00:00:00+00:00"
}

Python 示例：

import requests, time

API = "https://oratext.com/api/v1"
HEADERS = {"Authorization": "Bearer ora_sk_YOUR_KEY"}

with open("meeting.mp3", "rb") as f:
    r = requests.post(f"{API}/transcriptions", headers=HEADERS,
                      files={"file": f}, data={"mode": "summary", "wait": "true"})
job = r.json()
if not r.ok:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("done", "error", "rejected"):
    time.sleep(2)
    job = requests.get(f"{API}/transcriptions/{job['id']}", headers=HEADERS).json()

if job["status"] == "done":
    print(job["text"])
    print(job.get("mode_text"))
else:
    print("failed:", job["error"]["message"])

JavaScript（Node 18+）示例：

const API = "https://oratext.com/api/v1";
const headers = { Authorization: "Bearer ora_sk_YOUR_KEY" };

const res = await fetch(`${API}/transcriptions`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/podcast.mp3", wait: "true" }),
});
let job = await res.json();
if (!res.ok) throw new Error(job.error.message);

while (!["done", "error", "rejected"].includes(job.status)) {
  await new Promise(r => setTimeout(r, 2000));
  job = await (await fetch(`${API}/transcriptions/${job.id}`, { headers })).json();
}
console.log(job.status === "done" ? job.text : job.error.message);

限制

分钟数与你的套餐共用：免费版每天5分钟，高级版每月500分钟，旗舰版每月1000分钟。超出剩余分钟数的文件会在处理开始前被拒绝。
单个文件：最大200 MB、最长120分钟音频。
每个密钥的频率限制：每分钟10次转写/处理请求、60次状态查询。
每个账户最多5个有效密钥；不用的请在账户中及时撤销。

错误

错误以 JSON 返回：{"error": {"code": "…", "message": "…"}}。主要错误码：

HTTP	说明
`400`	bad_request / invalid_level / invalid_mode / url_invalid / url_blocked / url_failed——参数或 url 有误，详见 message。
`401`	API 密钥缺失、无效或已被撤销。
`402`	quota_exceeded：套餐剩余分钟数不足；响应中包含 remaining_minutes。
`403`	email_unverified、level_not_allowed 或 llm_limit——请确认邮箱；所请求级别超出套餐；或该转写的20次处理已用完。
`404`	not_found——此 API 密钥下没有该 id 的转写。
`409`	not_ready——转写尚未完成，请等待状态变为 done。
`413`	file_too_large / too_long：文件超过大小或时长限制。
`415`	unsupported_media：无法从文件中解码出音频。
`429`	rate_limited——每分钟请求过多，请放慢速度后重试。
`502`	llm_failed——文本处理失败，请稍后重试。

有问题？

在 Telegram 上联系我们：@oratextbot——回复很快，也乐意协助你完成集成。