生成を作成する
model、prompt、params、Idempotency-Key、公開応答フィールドを使って、非同期の Rivya API 生成ジョブを送信します。
2026年11月11日 最終レビュー
非同期の画像、動画、音声生成ジョブを送信するには、POST /api/v1/generations を使います。
チャットモデルには Chat API を使ってください。POST /api/v1/generations はチャットセッションや assistant メッセージを作成しません。
Suno Speech:シーンと入力した台本
Suno Speech: prompt はシンプル(params.customMode="false")ではシーン、詳細("true")では台本です。tone、variety、vocalGender、backgroundMusic は詳細専用で、シンプルでは省略します。params に別の script や prompt を入れないでください。
プロンプトの単位と全レイヤーの結果
GET /api/v1/models の max_prompt_length は prompt_length_unit と合わせて確認してください。utf8_bytes は空白と改行を含む原文の UTF-8 バイト数、utf16_code_units は JavaScript の UTF-16 コード単位数です。null は無制限や入力省略を意味しません。Gemini TTS はバイト単位です。
レイヤー分解の完了結果には、全ファイルの result.urls に加えて result.layers が含まれる場合があります。各レイヤーの z_index、URL、寸法、名前、説明、境界ボックスが提供された場合は保持してください。インデックス0がベース画像です。TypeScript SDK もこれらのフィールドを公開します。参照は選択したモデルでアップロードし、元の署名付きメタデータを渡してください。寸法や長さの自己申告だけでは検証を代替できません。
エンドポイント
API 有効化・利用権・有効なキーの generations:create または * と予約用残高が必要です。モデルリファレンス で対象 API の利用可否を確認してください。Lyrics など音声分類でも文字を返す場合があります。初回から冪等キーを送り、API 認証 に従います。
POST https://rivya.ai/api/v1/generations必須ヘッダー:
Authorization: Bearer rvya_sk_...
Content-Type: application/json推奨ヘッダー:
Idempotency-Key: your-unique-request-keyリクエスト body
形状上は model が必須で、prompt・params は任意ですがモデル・モードで必須や組み合わせ条件があります。client_request_id は任意の 128 文字以内の追跡値で、冪等キーではありません。例の URL・トークン・測定値は同じモデルへの自分の元の応答でまとめて置き換えてください。
{
"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: 必須の公開モデル IDprompt: プロンプトテキスト。多くのモデルで必須です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 エントリに含めてください。
seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, qwen-image-3-pro は元のモデル用アップロード応答を params.referenceMediaItems に mime_type → mimeType, width → width, height → height, size_bytes → sizeBytes, image_dimensions_token → imageDimensionsToken と対応付けます。アカウント・モデル・URL・情報が署名と一致する必要があり、欠落・期限切れ・不一致・偽造はタスク作成と予約前に拒否します。レイヤー分解はちょうど 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 から呼び出せるモードではありません。
署名動画情報が必要なら、元の応答を参照項目へ mime_type → mimeType, duration_seconds → durationSeconds, duration_token → durationToken, video_width → width, video_height → height, frames_per_second → framesPerSecond, video_bitrate_mbps → videoBitrateMbps, video_file_size_bytes → sizeBytes, video_metadata_token → videoMetadataToken と対応付けます。長さ・動画情報の両トークンを作成・予約前に検証します。音声も必要な元の mime_type・size_bytes・duration_token を mimeType・sizeBytes・durationToken として保持し、署名値を変更しないでください。
Wan 3.0 の入力と予約
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 は選択した版・解像度の単価に、要求出力秒数と検証済み参照動画秒数の合計を掛け、全体を一度だけ切り上げます。自動長は出力 30 秒分を予約します。現在の単価は Wan 3.0 API リファレンス を確認してください。有効な最終使用量が予約内なら精算して差額返却し、欠落・無効・超過なら予約を RECONCILIATION_REQUIRED のまま保持して自動追加請求しません。
Wan 3.0 の参照モードでは、画像は最大 10 枚、動画は最大 5 本、音声は最大 5 本です。動画と音声はそれぞれ 1~15 秒で、種類ごとに独立した合計 15 秒の上限があります。duration=-1 は参照動画と併用できません。動画入力がある場合、検証済み入力動画の秒数とリクエストした出力秒数の合計は 30 を超えてはいけません。
動画と音声のリップシンク例
volcengine-video-lip-sync は動画 1 本と音声 1 本を使う例です。数値は条件内ですがトークンは実際の署名ではありません。URL・トークン・MIME・測定値を対応する元のアップロード応答でまとめて置き換えてください。
{
"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": 13175000,
"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",
"sizeBytes": 1190444
}
]
}
}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 例
fetch 対応サーバーで RIVYA_API_KEY を設定します。HTTP 結果を確認してからタスクとして扱い、キーをブラウザーへ置かないでください。
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();
if (!response.ok) {
throw new Error(JSON.stringify(generation.error));
}
console.log(generation.id, generation.status);Python 例
requests とサーバーの RIVYA_API_KEY が必要です。30 秒のタイムアウトは HTTP 待機のみで、生成時間や失敗を決めません。各例の同じ冪等キーは同一要求の再試行用で、別の生成には別キーを使ってください。
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()
if not response.ok:
raise RuntimeError(generation.get("error"))
print(generation["id"], generation["status"])応答
金額と日時は例で、現在の価格や実測結果ではありません。例は送信後の processing で、final_credits は初期予約と同じ、RESERVED は未精算です。進行と精算は別に読み、API クレジット を確認してください。
id を保存して生成状態 を照会します。応答の紛失・不明だけで未作成とは分からず、ID があれば先に確認します。API Webhooks が有効で、状態が active の送信先がある場合、成功は SETTLED 後に通知し、失敗通知だけでは返却を証明しません。
{
"id": "task_public_id",
"status": "processing",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "RESERVED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:00:00.000Z",
"result": null,
"error": null
}冪等性
初回から Idempotency-Key を送り、再試行は同じアカウント・API キー・本文・指定済み client_request_id を維持します。保存応答はエラーも含め再生し、新規作成しません。最新状態ではないため生成状態 を使います。
本文違いや元応答の未保存では 409 idempotency_conflict になります。結果不明ならキーと本文を保持し、既存タスクと requestId を確認してください。新しいキーは別タスクと予約を作り得ます。ヘッダーは 128 文字超を切り詰め、追跡フィールドの上限とは別です。
よくある質問
client_request_id で重複を防げますか?
いいえ。追跡用なので、再生には冪等キーと同じ本文を使います。
別の API キーで再生できますか?
いいえ。同じ残高でも記録はアカウントと個別 API キーに属します。
要求失敗は返却済みですか?
それだけでは分かりません。ID があればタスクと精算を確認します。402 insufficient_credits は初期予約不足、他のクレジット処理失敗は 500 internal_error の場合があります。API エラー を確認してください。
