↓
Rivya AI 文件

建立生成任務

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

最近審閱於 2026/08/25

使用 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-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 參考圖片都必須使用原始模型綁定 Files API 回應中的 width、height、size_bytes 和 image_dimensions_token，並分別以 width、height、sizeBytes 和 imageDimensionsToken 傳送。token 缺失、過期、不相符或由使用者端自行編造時，請求會在建立任務及預留點數前失敗。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 傳送。系統會在建立任務及預留點數前驗證兩個已簽名 token。

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 在 480P、720P 或 1080P 下，會為每個要求的輸出秒數分別預留 8、16 或 32 點。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-Key。如果相同 key 和相同 request body 被重播，Rivya 可以回傳已儲存的公開回應，而不是建立重複任務。

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

相關頁面

模型 API 參考

查詢 Rivya API 模型 ID、可用狀態、支援模式、參數表、提示詞限制、參考媒體規則和模型詳情連結。

Chat API

使用 Rivya Chat API 發送非串流或 SSE 回合、API 建立的工作階段、file_id 圖片附件，並依 token 結算點數。

目錄

Endpoint
Request Body
Params 中的參考檔案
curl 範例
JavaScript 範例
Python 範例
回應
冪等性
相關頁面