生成を作成する

非同期の画像、動画、音声生成ジョブを送信するには、POST /api/v1/generations を使います。

チャットモデルには Chat API を使ってください。POST /api/v1/generations はチャットセッションや assistant メッセージを作成しません。

エンドポイント

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

必須ヘッダー:

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

推奨ヘッダー:

Idempotency-Key: your-unique-request-key

リクエスト 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: あなたのシステム側の任意のトレース ID

モデル固有の params については モデル API リファレンス を読んでください。

参照ファイルを 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 ではさらに、文書化された幾何制限内の画像が必ず 1 枚だけ必要です。

Grok Imagine Image 2.0 も同じ署名済み画像メタデータ境界を使います。テキストから画像を生成する場合は参照アイテムを送信せず、標準画像編集の場合は一意な署名済み JPEG、PNG、WebP アイテムを 1～5 件送信します。テキストからの画像生成では 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 は、相互排他的な 3 つの seedance_scene 値を使います。text はアップロード済みメディアを受け付けません。frames は先頭画像が 1 枚必須で、末尾画像を 1 枚任意で追加できます。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 で、リクエストした出力 1 秒あたりそれぞれ 8、16、32 クレジットを予約します。Prime は 1 秒あたり 12.2、25.2、50.4 クレジットを予約します。Rivya は合計予約額を 1 回だけ切り上げ、インテリジェント長さでは 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 を使ってください。同じキーと同じリクエスト body が再実行された場合、Rivya は重複タスクを作成せず、保存済みの公開応答を返せます。

同じキーが異なる入力で再利用された場合、API は idempotency_conflict を返します。

関連ページ

• 生成ステータス

• API Webhooks

• API クレジット

• API エラーと制限

• モデル API リファレンス