إنشاء توليد

استخدم POST /api/v1/generations لإرسال مهمة توليد غير متزامنة للصورة أو الفيديو أو الصوت.

بالنسبة إلى نماذج الدردشة، استخدم Chat API. لا ينشئ POST /api/v1/generations جلسات دردشة أو رسائل مساعد.

Endpoint

POST https://rivya.ai/api/v1/generations

Headers مطلوبة:

Authorization: Bearer rvya_sk_...
Content-Type: application/json

Header موصى به:

Idempotency-Key: your-unique-request-key

جسم الطلب

{
  "model": "z-image",
  "prompt": "A clean editorial product image on a soft studio background",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

الحقول:

• model: معرف نموذج عام مطلوب

• prompt: نص الموجه، وهو مطلوب في كثير من النماذج

• params: كائن معاملات خاص بالنموذج

• client_request_id: معرف تتبع اختياري من نظامك

اقرأ مرجع Model API من أجل params الخاصة بكل نموذج.

الملفات المرجعية داخل Params

بالنسبة إلى النماذج التي تقبل وسائط مرجعية مرفوعة، استدع أولا Files API. ثم مرر نتيجة الرفع عبر params الخاصة بالنموذج؛ لا تضف حقل files على المستوى الأعلى إلى طلب التوليد.

استخدم params.referenceMediaItems للتكاملات الجديدة:

{
  "model": "nano-banana-2-lite",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024,
        "sizeBytes": 482314,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  }
}

بالنسبة إلى مدخلات الصوت أو الفيديو التي تتطلب التحقق من المدة، أدرج duration_token العائد من /api/v1/files باسم durationToken في عنصر referenceMediaItems المرتبط.

تتطلب كل صورة مرجعية لنماذج Image5 قيم width وheight وsize_bytes وimage_dimensions_token من استجابة Files API الأصلية المرتبطة بالنموذج، وتُرسل بأسماء width وheight وsizeBytes وimageDimensionsToken. يؤدي غياب الرمز أو انتهاء صلاحيته أو عدم تطابقه أو إنشائه من جانب العميل إلى فشل الطلب قبل إنشاء المهمة وحجز الرصيد. ويتطلب Layer Decomposition أيضا صورة واحدة بالضبط ضمن الحدود الهندسية الموثقة له.

يخضع Grok Imagine Image 2.0 لمتطلبات بيانات الصور الوصفية الموقعة نفسها. لا ترسل أي عناصر مرجعية عند تحويل النص إلى صورة؛ أما لتحرير الصور القياسي فأرسل من 1 إلى 5 عناصر JPEG أو PNG أو WebP فريدة وموقعة. يقبل تحويل النص إلى صورة النسب 1:1 و2:3 و3:2 و16:9 و9:16؛ ويقبل تحرير الصور أيضا auto. لا يمكن استدعاء وضعي Segment Map وSegment Edit عبر Public API.

يتطلب كل فيديو مرجعي لنماذج Video8 قيم duration_seconds وduration_token وvideo_width وvideo_height وframes_per_second وvideo_bitrate_mbps وvideo_file_size_bytes وvideo_metadata_token من الاستجابة الأصلية المرتبطة بالنموذج. أرسلها بأسماء durationSeconds وdurationToken وwidth وheight وframesPerSecond وvideoBitrateMbps وsizeBytes وvideoMetadataToken. يجري التحقق من كلا الرمزين الموقعين قبل إنشاء المهمة وحجز الرصيد.

يستخدم Wan 3.0 ثلاث قيم متبادلة الاستبعاد لـ seedance_scene. لا يقبل text أي وسائط مرفوعة؛ ويتطلب frames صورة أولى ويسمح بصورة أخيرة اختيارية؛ ويقبل reference حزمة موقعة من الصور والفيديوهات والمقاطع الصوتية، لكن لا يمكن أن يكون الصوت الوسيط الوحيد. يجب أن تأتي كل عناوين URL المرجعية من عمليات رفع أصلية عبر Files API ومرتبطة بالنموذج. تظل اختصارات تحويل الملف إلى فيديو وتحويل الرابط إلى فيديو غير متاحة.

اضبط variant على standard أو prime، وresolution على 480P أو 720P أو 1080P، وaspect_ratio على adaptive أو 16:9 أو 4:3 أو 1:1 أو 3:4 أو 9:16. يقبل duration أعدادا صحيحة من 2 إلى 30، أو -1 للمدة الذكية؛ ويتحكم audio في الصوت الذي ينشئه النموذج، ويقبل seed قيما من 0 إلى 2147483647. يجب أن يحتوي الموجه بعد إزالة المسافات المحيطة على 1–20,000 حرف.

يحجز Wan 3.0 Standard مقدار 8 أو 16 أو 32 رصيدا لكل ثانية إخراج مطلوبة بدقة 480P أو 720P أو 1080P. ويحجز Prime مقدار 12.2 أو 25.2 أو 50.4 رصيدا في الثانية. تقرّب Rivya الحجز الإجمالي إلى الأعلى مرة واحدة؛ وتحجز المدة الذكية 30 ثانية. إذا كان الاستخدام الفعلي صالحا ولا يتجاوز الحجز، تُسوّى المعاملة ويُرد الفرق. أما إذا كان الاستخدام الفعلي مفقودا أو غير صالح أو أعلى من الحجز، فيظل الحجز كما هو وتدخل المعاملة في حالة المطابقة من دون خصم إضافي مخفي.

في وضع المرجع لـ Wan 3.0، أرسل 10 صور و5 فيديوهات و5 مقاطع صوتية كحد أقصى. تتراوح مدة كل مقطع فيديو أو صوت من 1 إلى 15 ثانية، ولكل نوع حد إجمالي منفصل قدره 15 ثانية. لا يمكن استخدام duration=-1 مع فيديو مرجعي؛ وعند وجود مدخل فيديو، يجب ألا يتجاوز مجموع ثواني فيديو الإدخال المتحقق منها وثواني الإخراج المطلوبة 30.

مثال على طلب Video8 لمهمة مزامنة شفاه باستخدام فيديو وصوت:

{
  "model": "volcengine-video-lip-sync",
  "prompt": "",
  "params": {
    "mode": "lite",
    "separate_vocal": "false",
    "open_scenedet": "false",
    "referenceMediaItems": [
      {
        "url": "https://.../source.mov",
        "kind": "video",
        "name": "source.mov",
        "mimeType": "video/quicktime",
        "durationSeconds": 12.4,
        "durationToken": "duration_token_from_files_api",
        "width": 1920,
        "height": 1080,
        "framesPerSecond": 30,
        "videoBitrateMbps": 8.5,
        "sizeBytes": 26214400,
        "videoMetadataToken": "video_metadata_token_from_files_api"
      },
      {
        "url": "https://.../dialogue.wav",
        "kind": "audio",
        "name": "dialogue.wav",
        "mimeType": "audio/wav",
        "durationSeconds": 12.4,
        "durationToken": "audio_duration_token_from_files_api"
      }
    ]
  }
}

مثال curl

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-preview-001" \
  -d '{
    "model": "z-image",
    "prompt": "A clean editorial product image on a soft studio background",
    "params": {
      "aspect_ratio": "1:1"
    }
  }'

مثال JavaScript

const response = await fetch("https://rivya.ai/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVYA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "product-preview-001"
  },
  body: JSON.stringify({
    model: "z-image",
    prompt: "A clean editorial product image on a soft studio background",
    params: { aspect_ratio: "1:1" }
  })
});

const generation = await response.json();
console.log(generation.id, generation.status);

مثال Python

import os
import requests

response = requests.post(
    "https://rivya.ai/api/v1/generations",
    headers={
        "Authorization": f"Bearer {os.environ['RIVYA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "product-preview-001",
    },
    json={
        "model": "z-image",
        "prompt": "A clean editorial product image on a soft studio background",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

generation = response.json()
print(generation["id"], generation["status"])

الاستجابة

{
  "id": "task_public_id",
  "status": "queued",
  "model": "z-image",
  "reserved_credits": 1,
  "final_credits": 0,
  "created_at": "2026-05-10T00:00:00.000Z",
  "updated_at": "2026-05-10T00:00:00.000Z",
  "result": null,
  "error": null
}

احفظ id واستطلع حالة التوليد. إذا ضبطت API Webhooks، يمكن لـ Rivya أيضا إرسال حدث generation.succeeded أو generation.failed موقع عندما تصل المهمة إلى حالة نهائية.

Idempotency

استخدم Idempotency-Key لإعادة المحاولة. إذا أعيد تشغيل المفتاح نفسه وجسم الطلب نفسه، يمكن لـ Rivya إعادة الاستجابة العامة المخزنة بدلا من إنشاء مهمة مكررة.

إذا أعيد استخدام المفتاح نفسه مع إدخال مختلف، يعيد API الخطأ idempotency_conflict.

صفحات ذات صلة

• حالة التوليد

• API Webhooks

• رصيد API

• أخطاء API وحدودها

• مرجع Model API