نقاط النهاية

الفيديو (مهام غير متزامنة)

أنشئ مهمة فيديو عبر POST /videos، وتابع حالتها بـ GET /videos/{id}، ثم نزّل الناتج، مع نماذج Veo وSora وطريقة المحاسبة عند الاكتمال.

جرّبه في ساحة التجربة

ولّد الفيديو بنماذج Veo 3.1 وSora 2 Pro وKling وSeedance وRunway وWan وHailuo وغيرها. يستغرق توليد الفيديو من عشرات الثواني إلى عدة دقائق، لذا يعمل كـ مهمة غير متزامنة: تنشئ مهمة، وتتابع حالتها، ثم تنزّل الناتج.

الخطوة	الطلب
1. الإنشاء	`POST /api/v1/videos`
2. المتابعة	`GET /api/v1/videos/{id}`
3. التنزيل	`GET /api/v1/videos/{id}/content?index=0`

إنشاء مهمة

POST https://api14.com/api/v1/videos

المعامل	النوع	مطلوب	الوصف
`model`	string	نعم	معرّف نموذج فيديو، مثل `google/veo-3.1-fast`.
`prompt`	string	نعم	ما الذي يحدث في الفيديو.
`duration`	number	لا	المدة بالثواني. الافتراضي أول مدة يدعمها النموذج.
`resolution`	string	لا	مثل `720p` و`1080p`. يجب أن يدعمها النموذج.
`aspect_ratio`	string	لا	مثل `16:9` و`9:16`.
`generate_audio`	boolean	لا	توليد مقطع صوتي حيث يكون مدعومًا (الافتراضي `true`).
`image`	string	لا	الإطار الأول كعنوان URL أو `data:` URI (تحويل الصورة إلى فيديو).

المدد والدقّات ونسب الأبعاد المدعومة لكل نموذج: GET /videos/models (عام) أو صفحة النموذج.

فحص الرصيد

قبل إرسال المهمة، تقدّر البوابة سعرها بـ المدة × السعر لكل ثانية للدقّة المطلوبة (وخيار الصوت). إذا كان رصيدك أقل من التقدير يفشل الطلب بالخطأ 402 insufficient_balance ولا يبدأ شيء.

الاستجابة

{
  "id": "vid_01JABCDEF",
  "status": "queued",
  "polling_url": "/api/v1/videos/vid_01JABCDEF"
}

متابعة المهمة

GET https://api14.com/api/v1/videos/{id}

{
  "id": "vid_01JABCDEF",
  "status": "completed",
  "generation_id": "gen-1791100000-abc",
  "unsigned_urls": ["/api/v1/videos/vid_01JABCDEF/content?index=0"],
  "usage": { "cost": 1.2 }
}

`status`	المعنى
`queued`	في انتظار المزوّد.
`in_progress`	قيد التصيير.
`completed`	اكتملت؛ يسرد `unsigned_urls` المخرجات.
`failed`, `cancelled`, `expired`	انتهت دون ناتج؛ راجع `error`. لا تُحاسَب.

تابع كل 5 إلى 10 ثوانٍ. الحساب الذي أنشأ المهمة وحده يستطيع قراءتها، وأي معرّف آخر يُعيد 404 not_found.

تنزيل الناتج

GET https://api14.com/api/v1/videos/{id}/content?index=0

يُعيد بايتات الفيديو (عادةً video/mp4) باستخدام مفتاح API الخاص بك. تشير عناوين المخرجات دائمًا إلى البوابة، لا إلى المزوّد الأصلي. إذا لم يكن الملف جاهزًا أو انتهت صلاحيته تحصل على content_unavailable.

مثال

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

// Video generation is asynchronous: submit, then poll until completed.
let job = await client.post("/videos", { body: {
  "model": "google/veo-3.1-fast",
  "prompt": "A drone shot over turquoise ocean waves at sunrise",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
} });
while (!["completed", "failed"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  job = await client.get(`/videos/${job.id}`);
}
console.log(job.status, job.unsigned_urls);

المحاسبة

تُحاسَب مرة واحدة عندما تصل المهمة إلى completed، بالتكلفة الفعلية لدى المزوّد. المهام الفاشلة والملغاة والمنتهية الصلاحية مجانية. وتكتمل المهام أيضًا في الخلفية، لذا فالمهمة التي لا تتابعها تُسوّى وتظهر في الاستهلاك (Usage).

الأخطاء

الحالة	الرمز	متى يحدث
402	`insufficient_balance`	الرصيد أقل من السعر المقدَّر للمهمة.
403	`plan_required`	خطتك لا تشمل نماذج الفيديو.
404	`model_not_found` / `not_found`	نموذج غير معروف، أو معرّف مهمة ليس لك.
502	`upstream_unavailable`	تعذّرت قراءة الحالة؛ أعد المحاولة.

راجع الأخطاء.