Rivya API でマルチモーダルワークフローを構築する

よい Rivya API 連携は、1つのモデルに1回リクエストを送るだけではありません。

実際のプロダクトワークフローの多くは、小さなチェーンになります。適切なモデルを選び、入力を準備し、必要なら参照ファイルをアップロードし、ジョブを送信し、ステータスを監視し、クレジットを扱い、結果が準備できたらプロダクトへ通知します。

この記事では計画の形を示します。最短で実行できる経路には Rivya API Quickstart を使い、正確なリクエストフィールドは API ドキュメントを参照してください。

プロダクト上の瞬間から始める

エンドポイントを選ぶ前に、プロダクト上の瞬間を1文で説明します。

例：

• 出品者が出品ブリーフを送信したら、商品画像の下書きを作成する。
• キャンペーン担当者が静止画の方向性を承認した後、短い動画コンセプトを生成する。
• 社内リサーチツール内で Chat turn を送り、レスポンスをユーザーへストリーミングで返す。
• 参照画像をアップロードし、対応モデルのリクエストを送信し、結果が準備できたらユーザーへ通知する。

この1文が、連携を API 呼び出しのゆるい寄せ集めにしないための軸になります。

コードを書く前にワークフローを対応付ける

リクエストスキーマを開く前に、この表を使います。

各 API 領域に存在理由があると分かるくらい、ワークフローは明確であるべきです。

ステップ1：連携用のキーを作成する

そのキーを使う特定のアプリ、環境、ワークフロー向けに API key を作成します。

1つのキーをすべてに使うのは避けます。目的別にキーへ名前を付けると、後のレビューが楽になります。

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

キーを保存する前に API Authentication を読んでください。完全な secret は一度だけ表示されるため、チームはすぐに正しいサーバー側 secret store へ保存する必要があります。

ステップ2：公開 API リストからモデルを選ぶ

手動テストで動いたからといって、モデルをハードコードしないでください。

API Models と Model API Reference を使って、次を確認します。

• 公開 model ID
• API 経由で利用可能か
• 対応入力モード
• プロンプトとパラメータの期待値
• Files API が必要か
• クレジット挙動と readiness notes

多くの連携はここで整理されます。手動の Studio テストに最適なモデルが、自動化されたプロダクトフローの最初のモデルとして正しいとは限りません。

ステップ3：初版に Files API を含めるか決める

モデルがテキスト入力だけで実行できるなら、初版は text-only に保ちます。

ワークフローが本当に参照メディアを必要とするときだけ、Files API を追加します。

追加する場合は、次を定義します。

• プロダクトが受け付けるファイル種別
• ファイルクリーンアップ手順の責任者
• アップロード失敗時の処理
• 返された file data をモデルパラメータへどう渡すか
• 同じファイルを再利用するのか、再アップロードするのか

これにより、見た目はきれいな生成ボタンの裏に、壊れやすいファイル体験が隠れることを防げます。

ステップ4：生成ジョブを1つ送信する

画像、動画、音声生成では、通常のパターンは次のとおりです。

1. model ID、プロンプト、対応 params を準備する
2. 安全な retry のために idempotency key を追加する
3. generation endpoint から送信する
4. public task ID を保存する
5. タスクが終端状態に到達するまでステータスを poll する

リクエスト形状には Create Generation を使い、結果処理には Generation Status を使います。

プロダクトは queued、processing、succeeded、failed をユーザーに見える状態として扱うべきです。ユーザーにシステム詳細を読ませたり、ジョブが遅い理由を推測させたりしないでください。

ステップ5：Chat モデルには Chat API を使う

Chat モデルは generation endpoint ではなく、Chat API を使うべきです。

これは、chat 作業の挙動が異なるため重要です。

• chat turn は API が作成した session に属せる
• non-streaming と SSE streaming ではユーザー体験が異なる
• 画像添付は Files API からの file ID を使う
• クレジット精算は通常の非同期メディアタスクではなく chat turn に従う

プロダクトが自前の画面内で assistant の回答を必要とするなら、Chat API が正しい経路かもしれません。ユーザーがまだアイデアを探索しているだけなら、Rivya Chat または Studio のほうが適している場合があります。

ステップ6：まず polling、次に Webhook

初版では、polling のほうが考えやすいです。

次の場合に API Webhooks を追加します。

• プロダクトに多くの非同期ジョブがある
• 待機中のクライアントが直接 poll すべきではない
• 下流システムが署名付き完了イベントを必要としている
• retry と duplicate handling がすでに設計されている

Webhook receiver は退屈で厳格であるべきです。署名を検証し、重複しても安全なイベントを受け入れ、1つのプロダクトレコードだけを更新し、安全に記録できることだけをログに残します。

ステップ7：プロダクト内でクレジットを見えるようにする

Rivya API は Studio と同じアカウントクレジットを使います。

連携側では、そのうちどれだけを表示するか決める必要があります。最低限、チームは次を知っているべきです。

• どのアカウントが API key を所有しているか
• どのワークフローがクレジットを消費できるか
• クレジットが少なすぎる場合に何が起きるか
• 生成失敗状態をどう説明するか
• クレジットと請求の質問をどこへ送るか

ユーザー向けウォレットモデルには、API Credits、Rivya のクレジットと請求、Rivya のクレジット、パック、プランの考え方 を使います。

小さな初版

よい初版は意図的に限定します。

例：

1. 1つの API key
2. 1つの選択済み画像モデル
3. まだファイルアップロードなし
4. 1つの生成リクエスト
5. 1つのステータス polling 経路
6. プロダクト内のシンプルな結果プレビュー
7. 1つの明確なクレジットエラーメッセージ

このバージョンで接続を証明してから、動く部品を増やします。

より完全なバージョン

初版が動いた後、より完全なワークフローでは次を追加できます。

• 参照画像や動画向けの Files API
• モデル固有のパラメータ制御
• プロダクトレコードに結び付いた idempotency
• 完了用の署名付き webhooks
• assistant turn 向けの Chat API
• chat が live output を必要とする場合のサーバー側 event stream
• 失敗ジョブ向けの admin または support view

それぞれの追加は、実際のプロダクト上の必要に答えるべきです。デモを大きく見せるだけなら、省きます。

よくある連携ミス

次のパターンは避けます。

• 最初からすべての API 機能を入れる
• アカウント所有者にクレジット使用量を見せない
• Studio だけの前提を API フローへ持ち込む
• ファイルアップロードを後付けの細部として扱う
• idempotency なしで生成リクエストを retry する
• 非同期生成にすべきジョブに Chat API を使う
• chat turn に generation endpoint を使う
• API key、webhook secret、一時ファイル詳細の全体をログに残す

最も安全な API ワークフローは、所有、状態、失敗処理を明確にします。

次に進むページ

• 公開 API ハブは Developers から始めます。
• 最初のリクエストを実行するには Rivya API Quickstart を使います。
• model ID を選ぶ前に API Models を使います。
• モデルが本当に参照メディアを必要とするときだけ Files API を使います。
• chat turn と streaming chat responses には Chat API を使います。
• polling だけでは足りなくなったら API Webhooks を使います。
• ワークフローにまだ人間の探索が必要なら、自動化する前に Rivya API を Studio の代わりに使うタイミング を読んでください。