model، prompt، params، Idempotency-Key، اور public response fields کے ساتھ asynchronous Rivya API generation jobs submit کریں۔

Asynchronous image، video، یا audio generation job submit کرنے کے لیے POST /api/v1/generations استعمال کریں۔

Chat models کے لیے Chat API استعمال کریں۔ POST /api/v1/generations chat sessions یا assistant messages create نہیں کرتا۔

اینڈ پوائنٹ

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

درکار headers:

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

Recommended header یہ ہے:

Idempotency-Key: your-unique-request-key

Request body

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

Fields یہ ہیں:

model: required public model ID
prompt: prompt text، بہت سے models کے لیے required
params: model-specific parameter object
client_request_id: آپ کے system سے optional trace ID

Model-specific params کے لیے Model API Reference پڑھیں۔

Params میں reference files

Uploaded reference media accept کرنے والے models کے لیے پہلے Files API call کریں۔ پھر upload result کو model params کے ذریعے pass کریں؛ generation request میں top-level files field شامل نہ کریں۔

نئی integrations کے لیے params.referenceMediaItems استعمال کریں:

{
  "model": "nano-banana-2",
  "prompt": "اس product photo کو clean editorial catalog page کے لیے restyle کریں",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  }
}

جن audio یا video inputs کو duration verification چاہیے ہو، ان میں /api/v1/files سے returned duration_token کو related referenceMediaItems entry پر durationToken کے طور پر شامل کریں۔

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": "soft studio background پر clean editorial product image",
    "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: "soft studio background پر clean editorial product image",
    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": "soft studio background پر clean editorial product image",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

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

Response

{
  "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 save کریں اور Generation status poll کریں۔ اگر آپ API Webhooks configure کرتے ہیں، تو task کے terminal state تک پہنچنے پر Rivya signed generation.succeeded یا generation.failed event بھی send کر سکتا ہے۔

Idempotency

Retries کے لیے Idempotency-Key استعمال کریں۔ اگر same key اور same request body replay ہوں تو Rivya duplicate task create کرنے کے بجائے stored public response return کر سکتا ہے۔

اگر same key مختلف input کے ساتھ دوبارہ استعمال ہو تو API idempotency_conflict return کرتی ہے۔

Generation بنائیں