よい Rivya API 連携は、1つのモデルに1回リクエストを送るだけではありません。
実際のプロダクトワークフローの多くは、小さなチェーンになります。適切なモデルを選び、入力を準備し、必要なら参照ファイルをアップロードし、ジョブを送信し、ステータスを監視し、クレジットを扱い、結果が準備できたらプロダクトへ通知します。
この記事では計画の形を示します。最短で実行できる経路には Rivya API Quickstart を使い、正確なリクエストフィールドは API ドキュメントを参照してください。
プロダクト上の瞬間から始める
エンドポイントを選ぶ前に、プロダクト上の瞬間を1文で説明します。
例：
出品者が出品ブリーフを送信したら、商品画像の下書きを作成する。キャンペーン担当者が静止画の方向性を承認した後、短い動画コンセプトを生成する。社内リサーチツール内で Chat turn を送り、レスポンスをユーザーへストリーミングで返す。参照画像をアップロードし、対応モデルのリクエストを送信し、結果が準備できたらユーザーへ通知する。
この1文が、連携を API 呼び出しのゆるい寄せ集めにしないための軸になります。
コードを書く前にワークフローを対応付ける
リクエストスキーマを開く前に、この表を使います。
| ワークフロー手順 | プロダクト上の問い | API 領域 |
|---|---|---|
| アカウントアクセス | どの Rivya アカウントが使用量を持つか？ | API Authentication |
| モデル選択 | この仕事に合う公開 model ID はどれか？ | API Models |
| 参照入力 | モデルにアップロード済みメディアが必要か？ | Files API |
| 生成 | これは非同期の画像、動画、音声ジョブか？ | Create Generation |
| Chat | これは生成ジョブではなく chat model turn か？ | Chat API |
| ステータス | 結果が準備できたことをプロダクトはどう知るか？ | Generation Status |
| 完了イベント | 別システムが署名付きコールバックを受け取るべきか？ | API Webhooks |
| クレジット | チームはコストをどう理解するか？ | API Credits |
各 API 領域に存在理由があると分かるくらい、ワークフローは明確であるべきです。
ステップ1：連携用のキーを作成する
そのキーを使う特定のアプリ、環境、ワークフロー向けに API key を作成します。
1つのキーをすべてに使うのは避けます。目的別にキーへ名前を付けると、後のレビューが楽になります。
production-image-workflowstaging-video-testsinternal-chat-assistantwebhook-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つ送信する
画像、動画、音声生成では、通常のパターンは次のとおりです。
model ID、プロンプト、対応 params を準備する
安全な retry のために idempotency key を追加する
generation endpoint から送信する
public task ID を保存する
タスクが終端状態に到達するまでステータスを 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つの API key
1つの選択済み画像モデル
まだファイルアップロードなし
1つの生成リクエスト
1つのステータス polling 経路
プロダクト内のシンプルな結果プレビュー
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 の代わりに使うタイミング を読んでください。
