デプロイで Public API が有効になっており、アカウントに利用権限がある場合、Rivya API は自社のプロダクト、スクリプト、ワークフローから Rivya の対応済みモデル機能を使うための開発者向け契約です。
Rivya Studio とは別のプロダクトではありません。同じアカウント境界、同じクレジットウォレット、Rivya 全体でユーザーが見る同じ公開モデルレイヤーを使います。違いは作業の始まり方です。Studio でクリックして進める代わりに、アプリケーションが API key 付きでリクエストを送ります。
エンドポイント詳細が必要なら、Rivya API Overview と Rivya API Quickstart から始めてください。この記事はプロダクトレベルの説明です。API は何のためにあるのか、どこに合うのか、いつ最初の経路にすべきではないのかを扱います。
短く言うと
Rivya API v1 では、利用条件を満たしたサインイン済みアカウントが API キーを作成し、ウェブインターフェイスの外から API 対応の Rivya モデル機能を呼び出せます。開発者向けページが示すのは実装済みの契約です。実際にリクエストを実行できるかは、現在のデプロイ、アカウント権限、モデルの提供状況で決まります。
実装済みの API 機能は次のとおりです。
API モデルリストによるモデル発見
非同期の画像、動画、音声生成ジョブ
参照メディアを必要とするモデル向けの Files API アップロード
公開タスク ID による生成ステータス polling
アカウントクレジット確認
任意の SSE streaming を含む Chat API turns
デプロイで Webhook が有効な場合の、生成完了向け署名付きイベント
クライアントラッパーがほしいチーム向けの TypeScript SDK beta
公開開発者ハブは Developers です。ガイド付き概要、API key 設定へのリンク、安全なデバッガーフローを見たい場合に最適な入口です。
Rivya に API がある理由
人がまだモデルを選び、プロンプトを整え、出力をレビューし、次に何をするか決めているなら、Studio が役に立ちます。
その判断が反復可能なプロダクトまたは運用ワークフローになったとき、API が役に立ちます。
API アクセスが有効な場合の一般的な例は次のとおりです。
ユーザーがブリーフを送信した後、プロダクトが画像バリエーションを生成したい
マーケティングワークフローが構造化されたキャンペーン入力からビジュアルドラフトを作りたい
内部ツールがブラウザを開くよう人に頼まず、動画または音声ジョブを送信したい
サポートまたはコンテンツシステムが、自分のインターフェイス内に chat モデル turn を置きたい
バックエンドサービスが生成ジョブ完了時に署名付き callback を受け取りたい
こうした場合、Rivya API は、請求、モデル選択、タスク状態のために別スタックを作るのではなく、同じ Rivya アカウントへ作業をつなぎます。
API が置き換えないもの
API は、Rivya を直接使うすべての理由を置き換えるものではありません。
次の場合は、Studio または公開作業面を使います。
プロンプトにまだ人の探索が必要
モデル選択が安定していない
クリエイターが出力を視覚的に比較する必要がある
プロジェクトが保存済み履歴と手動レビューに依存している
チームがどの入力と出力形式を反復可能にすべきか決めていない
ワークフローが自動化できるほど明確になったら、API を使います。
この境界は重要です。曖昧なクリエイティブ質問は、通常まず Studio に属します。予測可能な入力を持つ既知のプロダクトフローは、API へ移せます。
主な構成要素
API は6つの接続された部品として考えます。
| 構成要素 | 扱うもの | 次に読む場所 |
|---|---|---|
| API キー | アカウントからのサーバー間アクセス | API 認証 |
| モデル | 公開モデル ID と利用準備状況 | API モデル |
| 生成 | 非同期の画像、動画、音声タスク | 生成タスクの作成 |
| ファイル | 参照画像、動画、音声のアップロード | ファイル API |
| チャット | 通常形式またはストリーミング形式のチャット応答 | チャット API |
| Webhook | 有効な場合に生成タスクの完了を知らせる署名付きイベント | API Webhook |
リクエストとレスポンスの形は API ドキュメントが正本です。この記事は、どの部品が最初に必要かを判断する助けになります。
クレジットの仕組み
API 使用量は、Studio と同じ Rivya アカウントのクレジットウォレットから引かれます。
つまり API は匿名で使えるモデル中継サービスではありません。リクエストは Rivya アカウントに紐づき、そのアカウントで作成した API キーを使い、API クレジットで説明しているプロダクト共通のクレジット規則に従います。
これはチームにとって有用です。Studio の実験と API 使用量が1つの運用モデルに留まるからです。モデルを手動でテストし、反復可能な部分を統合へ移しても、2つ目の請求レイヤーを作る必要はありません。
ファイルの位置づけ
一部のモデルはテキストだけで実行できます。別のモデルは参照画像、動画、音声ファイルを必要とします。
API 統合では、これらの参照素材は Files API を通すべきです。アップロードにより、対応するモデルパラメータへ渡せる管理済みファイルレコードが作られます。
実用ルールはシンプルです。
モデルがテキストのみの入力を受け付けるなら、generation endpoint から始める
モデルが参照メディアを必要とするなら、先にファイルをアップロードする
モデルが画像添付付きの chat モデルなら、Chat API と file IDs を使う
ブラウザだけのアップロードフローや保存済み Studio セッションを前提に統合を設計しないでください。API には理由があって独自の公開ファイル境界があります。
Webhooks が役立つ場所
polling は最初の統合経路として最も簡単です。生成ジョブを送信し、公開タスク ID を保存し、成功または失敗するまで poll します。
デプロイで Webhook が有効な場合、統合が本番運用に近づくほど役に立ちます。
worker にすべてのジョブを polling させたくない
アプリが生成完了時にレコードを更新する必要がある
安全に再試行できる署名付きイベントがほしい
失敗ジョブを明確な復旧経路へ移す必要がある
署名付きイベント契約は API Webhooks を参照してください。これを前提に設計する前に、機能が利用可能か確認します。Webhook の受信処理は必要最小限にし、署名を検証して重複イベントを処理し、機密値をログへ残さないでください。
よい最初の API プロジェクト
最初の API プロジェクトは、小さく具体的であるのが通常は最適です。
例えば次です。
デプロイとアカウントで API アクセスが有効か確認する
設定で API キーを作成する
モデルリストを呼び出す
API 対応モデルを1つ選ぶ
冪等性キー付きで生成ジョブを1件送信する
ステータスエンドポイントをポーリングする
前後のクレジットを確認する
その後で、デプロイが提供する Files API、Chat API、Webhook を追加する
この経路なら、最初のテストにすべての API 機能を混ぜ込まずに、動く統合を得られます。
API が間違った開始点になるとき
API は次の場合、おそらく正しい最初のステップではありません。
チームがまだモデルファミリーを選んでいない
望む出力が実行ごとに変わっている
プロンプトが手動の感覚とレビューに依存している
統合により、理解すべき人からクレジット使用量が見えにくくなる
プロダクトには自動化より先に公開デモが必要
その場合は、画像、動画、音声、チャット、またはAI モデルから始めます。手順を繰り返せる状態になったら、安定した部分を API へ移します。
次に進むページ
公開 API ハブとデバッガーは Developers を開いてください。
最初の安全なリクエストを行うには Rivya API Quickstart を読んでください。
サーバーにキーを置く前にAPI 認証を読んでください。
モデル ID を選ぶ前にAPI モデルを読んでください。
プロダクト境界がまだ不明なら Studio ではなく Rivya API を使うべきとき を読んでください。
画像、動画、音声、chat の完全な統合を計画しているなら、Rivya API でマルチモーダル AI ワークフローを構築する方法 を読んでください。
