توليد الوسائط

توليد الوسائط غير المتزامن: الصور والفيديو والتعليق الصوتي (TTS) وتحويل الكلام إلى نص والموسيقى والـ 3D. تنشئ مهمة ثم تتبّع النتيجة. تجد قائمة الطرازات الكاملة في media-models catalog؛ أما الـ webhooks والأخطاء والفوترة ففي webhook section.

يُعيد الإنشاء 202 مع { ok: true, jobId, status: "processing" }. استعلم بـ GET /api/media/jobs/{jobId} حتى status: "success"، ثم خُذ resultUrls.

# 1. create a generation job
curl https://getvibeapi.com/api/media/generate \
  -H "Authorization: Bearer $GETVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1",
    "prompt": "a cat on a skateboard, slow motion"
  }'
# → {"ok":true,"jobId":"...","status":"processing"}

إلى جانب model وprompt، يمكنك تمرير خيارات إضافية في opts. وتعتمد المجموعة على النموذج. أما العقد الكامل القابل للقراءة آليًا فهو متاح عبر GET /api/model-capabilities (أو GET /api/model-capabilities/{model} لنموذج محدّد).

خيارات URL ‏(image_url، input_urls، mask_url وما عداها) هي روابط يجلبها المزوّد، لذا تقبل فقط عناوين https:// عامة. ويُرفض أي نص data:image/...;base64,… مضمَّن في أحد تلك الحقول مع 400.

لإرسال ملفك الخاص، استخدم حقل *_base64 المطابق بدلًا من ذلك: تخزّن الخدمة البايتات وتنشرها وتمرّر الرابط الناتج إلى المزوّد. حتى 16 ملفًا لكل طلب في input_base64.

يقبل POST /api/media/generate و POST /api/media/price النص نفسه، لذا يمكنك تسعيره ثم إرساله دون تغيير. لا توجد حقول أخرى على المستوى الأعلى: يُرفض أي حقل غير معروف على كلا النقطتين بالرمز 400 وكود unknown_field مع تسميته (field, fields)، مع strict أو بدونه. تُوضع معلمات التوليد داخل opts.

يمكن إرسال أي ملف مصدر بثلاث طرق: كرابط (image_url، audio_url، video_url…)، أو كبايتات مضمَّنة (image_base64، audio_base64، video_base64…)، أو كمعرّف ملفك الخاص من POST /v1/files. حقول المعرّف مدرجة في requestJsonSchema لكل عملية ومقبولة في الوضع الصارم.

بالنسبة إلى النماذج التي يتبع طول مخرجاتها مسارًا مرفوعًا — kling-ai-avatar، omnihuman-v2، omnihuman-2-0، omnihuman-v1.5، omnihuman-1-5، volcengine-lipsync (audio)، kling-motion-control، wan-animate، topaz-video-upscale، p-video-edit (video)، lipsync-2-pro، sync-3، react-1 (both inputs) — تقيس /api/media/price وفحص ما قبل التنفيذ max_price_rub على /api/media/generate ذلك الملف من جانب الخادم (link أو data: URI أو base64 أو *_file_id)، وتحتسب السعر وفق الثواني المقاسة. تتضمن الاستجابة sourceSeconds (outputSeconds for lip-sync)، ويذكر estimateReason أنه تم قياس الطول. وإذا تعذّر قراءة الملف، يبقى السعر مستندًا إلى أساسه السابق (ثانية واحدة أو تقدير الكتالوج أو الحد الأقصى للمسار)، ويذكر estimateReason ذلك. وتساوي التكلفة معدل الثانية × عدد الثواني التي تم عرضها فعليًا، على ألا تتجاوز max_price_rub مطلقًا. ويُقبل opts.duration في هذه النماذج ويتم تجاهله مع تحذير param_ignored.

Create: { name, consent: true, engine, audio_url | audio_base64 } or several recordings samples: [{ audio_url } | { audio_base64 }, …] (engine: "elevenlabs" only). An ElevenLabs voice is used by voice-clone-tts and by the Voice Changer (elevenlabs-voice-changer). Appending recordings to an ElevenLabs voice is free. Every recording is downloaded and measured before the supplier is called: a refusal changes and charges nothing.

مغيّر الصوت والمحاذاة القسرية

عندما لا يصل تأكيد البدء من المورّد، تبقى المهمة في الحالة: "submitting" مع stage: "submission_unknown"، وerrorCode: "media_submission_uncertain"، وfailure.advice: "reconcile_first" — واصل الاستعلام عن نفس jobId ولا تنشئ نسخة مكرّرة. لاختبار هذا المسار دون أي تكلفة، أرسل POST /api/media/generate بمفتاح sandbox مع الترويسة x-pv-sandbox-outcome: submission_uncertain. تكون الإجابة 202 عادية مع jobId؛ ويجيب الاستعلام عنه كإرسال غير معروف لمدة 60 ثانية، ثم كمهمة لم تبدأ قط (failure.code: "submission_not_started"، charged: false). لا يُخزَّن شيء ولا يُرسَل إلى أي مورّد ولا يُحتسب أي مبلغ. أما المفتاح العادي مع هذه الترويسة فيحصل على 400 sandbox_outcome_requires_sandbox_key.

المسار نفسه المستخدم لبقية عمليات التوليد: ضع اسم طراز STT في model، واترك prompt سلسلة فارغة، ومرّر التسجيل في opts.audio_url. يصل النص المكتوب في resultText عند GET /api/media/jobs/{id}؛ ويبقى resultUrls فارغاً — فالنسخ الكتابي لا ينتج أي ملف.

# speech-to-text: create the job, then read the transcript
curl https://getvibeapi.com/api/media/generate \
  -H "Authorization: Bearer $GETVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "whisper-large-v3-turbo",
    "prompt": "",
    "opts": {
      "audio_url": "https://example.com/meeting.mp3",
      "language_code": "en"
    }
  }'
# → {"ok":true,"jobId":"JOB_ID","status":"processing","priceRub":0.03}

curl https://getvibeapi.com/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $GETVIBE_API_KEY"
# → {"status":"success","resultText":"the transcribed text…","resultUrls":[],"priceRub":0.03}

النماذج

• whisper-large-v3-turbo — 0.00025 دولار لكل دقيقة من الصوت. الأرخص والأسرع، ويدعم 99 لغة.
• nemotron-asr-multilingual — 0.00025 دولار لكل دقيقة. تعرّف آلي متعدد اللغات من NVIDIA، ويضيف علامات الترقيم من تلقاء نفسه.
• whisper-large-v3 — 0.000563 دولار لكل دقيقة. Whisper كامل: أبطأ من turbo، لكنه أدق مع الصوت المشوّش.
• universal-2 — 0.003125 دولار لكل دقيقة.
• speech-to-text — 0.01 دولار لكل دقيقة (ElevenLabs Scribe). يدعم تمييز المتحدثين ووسوم الأحداث الصوتية.

المعلمات

الصيغ والحدود

تُقبل mp3 و wav و m4a/mp4 و flac و ogg/opus و webm. الحد الأقصى لحجم الملف 25 ميغابايت — أي نحو 26 دقيقة من mp3 بمعدل 128 kbps، أو عدة ساعات من الكلام بصيغة opus. وكل ما يتجاوز ذلك يُرفض فورًا برسالة صريحة ولا تُحتسب له فاتورة؛ قسّم التسجيل بدلًا من ذلك.

لتجنب الاستقصاء الدوري، سجّل عنوانًا واحدًا mediaWebhookUrl في لوحة التحكم. وعند اكتمال المهمة (نجاحًا أو خطأً)، تُجري الخدمة حتى خمس محاولات تسليم لـ POST بجسم JSON:

// POST to your mediaWebhookUrl when a job finishes
{
  "jobId": "...",
  "status": "success",            // or "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://getvibeapi.com/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

رابط نتيجة التوليد (صورة أو فيديو أو صوت أو نموذج 3D) من resultUrls. استخدمه كما يُعيده هو: يُفتح دون مفتاح API ويعمل في <img> أو <video> أو المتصفح. المزوّد مخفي: يُستنبط العنوان الأعلى من جهة الخادم ولا يراه العميل قط.

# The signed URL is returned in resultUrls of the /api/media/jobs/{id} response
# or in the webhook body. Opens directly in the browser / <img> — no key needed.
https://getvibeapi.com/api/media/file/JOB_ID/0?sig=HMAC_SIGNATURE