توثيق API
Production API uses async jobs.
External API keys use resumable uploads, job creation, status polling, and webhook callbacks.
البدء السريع
أنشئ مفتاح API من لوحة التحكم (يبدأ بـ ahk_). استخدم مسار async: رفع الملف، إنهاء الرفع، ثم إنشاء المهمة.
مسار async من ثلاث خطوات
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 فقط؛ مسار الصوت القصير يبقى داخليًا داخل المنتج.
| 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 حد طلبات في الدقيقة. عند تجاوز الحد يعود 429 مع header باسم Retry-After.
احصل على مفتاح API
افتح لوحة التحكم، انتقل إلى خطة تدعم API، وأنشئ مفتاحًا يبدأ بـ ahk_.
احصل على مفتاح API