使用 model、prompt、params、Idempotency-Key 和公開回應欄位提交 Rivya API 非同步生成任務。

使用 POST /api/v1/generations 提交非同步圖片、影片或音訊生成任務。

對於聊天模型，請使用 Chat API。POST /api/v1/generations 不會建立 chat sessions 或 assistant messages。

Endpoint

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

必要 headers：

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

建議 header：

Idempotency-Key: your-unique-request-key

Request Body

{
  "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：必填的公開模型 ID
prompt：提示文字，許多模型都會要求
params：模型專屬參數物件
client_request_id：來自你系統的選用 trace ID

請閱讀模型 API 參考了解模型專屬 params。

Params 中的參考檔案

對於接受已上傳參考媒體的模型，請先呼叫 Files API。接著透過模型 params 傳入上傳結果；不要在生成請求中加入頂層 files 欄位。

新的整合請使用 params.referenceMediaItems：

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

對於需要時長驗證的音訊或影片輸入，請將 duration_token（由 /api/v1/files 回傳）作為 durationToken 放入對應的 referenceMediaItems 項目。

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-Key。如果相同 key 和相同 request body 被重播，Rivya 可以回傳已儲存的公開回應，而不是建立重複任務。

如果相同 key 以不同輸入重複使用，API 會回傳 idempotency_conflict。

建立生成任務