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.mp3

3. 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 فقط؛ مسار الصوت القصير يبقى داخليًا داخل المنتج.

EndpointPurposeLimit
POST /v1/audio/ingestCreate an async upload sessionBest effort
POST /v1/audio/uploadsCreate upload sessionUp to 2 GB
GET /v1/audio/uploads/:idRecover or inspect upload state
POST /v1/audio/uploads/:id/completeFinalize upload sessionIdempotent
POST /v1/audio/jobsCreate async transcription jobCompleted upload required
GET /v1/audio/jobs/:idPoll 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')
}

أكواد الخطأ

StatusCodeMeaning
400invalid_requestMissing or invalid request field
401unauthorizedAPI key missing or invalid
402insufficient_creditsWorkspace has no available quota
403plan_requiredPlan does not include API access
413file_too_largeUpload exceeds the supported object limit
415unsupported_media_typeAudio/video format is not supported
429rate_limit_exceededRetry after the returned Retry-After value
500 / 502internal_errorInclude x-orpheus-request-id when contacting support

حدود الطلبات

لكل مفتاح API حد طلبات في الدقيقة. عند تجاوز الحد يعود 429 مع header باسم Retry-After.

احصل على مفتاح API

افتح لوحة التحكم، انتقل إلى خطة تدعم API، وأنشئ مفتاحًا يبدأ بـ ahk_.

احصل على مفتاح API

راجع الأسعار

الخطط تحدد الدقائق، التوازي، وإمكانيات API.

الأسعار