API 文档
生产 API 统一走异步任务。
外部 API key 使用可恢复的上传、任务创建、状态查询和 webhook 回调。短音频实时路径属于内部产品能力，不在公开 token API 中开放。
快速开始
先在 console 创建 API key（ahk_ 开头）。外部集成按上传、完成上传、创建任务这三步异步流程处理。
长音频三步异步工作流
1. POST /v1/audio/uploads
curl https://audio.niumedia-ai.com/v1/audio/uploads \
-H "Authorization: Bearer $ORPHEUS_KEY" \
-H "Content-Type: application/json" \
-d '{"file_name":"meeting.mp3","mime_type":"audio/mpeg","size_bytes":52428800}'2. PUT $UPLOAD_URL
curl $UPLOAD_URL \
-X PUT \
-H "Content-Type: audio/mpeg" \
--data-binary @meeting.mp33. POST /v1/audio/jobs
# Complete the upload session, then create the job.
curl https://audio.niumedia-ai.com/v1/audio/uploads/$UPLOAD_ID/complete \
-H "Authorization: Bearer $ORPHEUS_KEY" \
-X POST
curl https://audio.niumedia-ai.com/v1/audio/jobs \
-H "Authorization: Bearer $ORPHEUS_KEY" \
-H "Content-Type: application/json" \
-d '{"upload_id":"$UPLOAD_ID","task":"transcribe","callback_url":"https://your-app.com/webhook"}'端点总览
公开 API 只暴露 async 合同。console workbench 的短音频快速路径在产品内部处理，不作为公开 API 文档或 token 能力开放。
| Endpoint | Purpose | Limit |
|---|---|---|
POST /v1/audio/ingest | Create an async upload session | Best effort |
POST /v1/audio/uploads | Create upload session | Up to 2 GB |
GET /v1/audio/uploads/:id | Recover or inspect upload state | — |
POST /v1/audio/uploads/:id/complete | Finalize upload session | Idempotent |
POST /v1/audio/jobs | Create async transcription job | Completed upload required |
GET /v1/audio/jobs/:id | Poll job status or fetch result | — |
Webhook 回调
创建任务时传 callback_url。任务到终态后 Orpheus 发送一次签名 POST；非 2xx 最多重试 3 次。
- Header:
X-Orpheus-Signature - Format:
t=<unix_seconds>,v1=<hmac_sha256_hex> - Signed payload:
<timestamp>.<raw_body> - Replay window: reject timestamps older than 5 minutes
import crypto from 'node:crypto'
export function verify(rawBody: string, sigHeader: string, secret: string) {
const parts = Object.fromEntries(sigHeader.split(',').map((p) => p.split('=', 2)))
const timestamp = parseInt(parts.t, 10)
if (Math.abs(Date.now() / 1000 - timestamp) > 300) throw new Error('timestamp too old')
const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))) throw new Error('bad signature')
}错误码
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing or invalid request field |
| 401 | unauthorized | API key missing or invalid |
| 402 | insufficient_credits | Workspace has no available quota |
| 403 | plan_required | Plan does not include API access |
| 413 | file_too_large | Upload exceeds the supported object limit |
| 415 | unsupported_media_type | Audio/video format is not supported |
| 429 | rate_limit_exceeded | Retry after the returned Retry-After value |
| 500 / 502 | internal_error | Include x-orpheus-request-id when contacting support |
限流
每个 API key 有独立 RPM 限额。超限返回 429，并带 Retry-After header。