Rivya API とは？

Rivya API は、自分のプロダクト、スクリプト、ワークフローから Rivya のモデル機能を使うための開発者向け経路です。

Rivya Studio とは別のプロダクトではありません。同じアカウント境界、同じクレジットウォレット、Rivya 全体でユーザーが見る同じ公開モデルレイヤーを使います。違いは作業の始まり方です。Studio でクリックして進める代わりに、アプリケーションが API key 付きでリクエストを送ります。

エンドポイント詳細が必要なら、Rivya API Overview と Rivya API Quickstart から始めてください。この記事はプロダクトレベルの説明です。API は何のためにあるのか、どこに合うのか、いつ最初の経路にすべきではないのかを扱います。

短く言うと

Rivya API v1 では、サインイン済みアカウントが API keys を作成し、ウェブインターフェイスの外から Rivya モデル機能を呼び出せます。

現在の API の範囲には次が含まれます。

• API モデルリストによるモデル発見
• 非同期の画像、動画、音声生成ジョブ
• 参照メディアを必要とするモデル向けの Files API アップロード
• 公開タスク ID による生成ステータス polling
• アカウントクレジット確認
• 任意の SSE streaming を含む Chat API turns
• 生成完了向けの署名付き Webhooks
• クライアントラッパーがほしいチーム向けの TypeScript SDK beta

公開開発者ハブは Developers です。ガイド付き概要、API key 設定へのリンク、安全なデバッガーフローを見たい場合に最適な入口です。

Rivya に API がある理由

人がまだモデルを選び、プロンプトを整え、出力をレビューし、次に何をするか決めているなら、Studio が役に立ちます。

その判断が反復可能なプロダクトまたは運用ワークフローになったとき、API が役に立ちます。

よくある例：

• ユーザーがブリーフを送信した後、プロダクトが画像バリエーションを生成したい
• マーケティングワークフローが構造化されたキャンペーン入力からビジュアルドラフトを作りたい
• 内部ツールがブラウザを開くよう人に頼まず、動画または音声ジョブを送信したい
• サポートまたはコンテンツシステムが、自分のインターフェイス内に chat モデル turn を置きたい
• バックエンドサービスが生成ジョブ完了時に署名付き callback を受け取りたい

こうした場合、Rivya API は、請求、モデル選択、タスク状態のために別スタックを作るのではなく、同じ Rivya アカウントへ作業をつなぎます。

API が置き換えないもの

API は、Rivya を直接使うすべての理由を置き換えるものではありません。

次の場合は、Studio または公開作業面を使います。

• プロンプトにまだ人の探索が必要
• モデル選択が安定していない
• クリエイターが出力を視覚的に比較する必要がある
• プロジェクトが保存済み履歴と手動レビューに依存している
• チームがどの入力と出力形式を反復可能にすべきか決めていない

ワークフローが自動化できるほど明確になったら、API を使います。

この境界は重要です。曖昧なクリエイティブ質問は、通常まず Studio に属します。予測可能な入力を持つ既知のプロダクトフローは、API へ移せます。

主な構成要素

API は6つの接続された部品として考えます。

リクエストとレスポンスの形は API ドキュメントが正本です。この記事は、どの部品が最初に必要かを判断する助けになります。

クレジットの仕組み

API 使用量は、Studio と同じ Rivya アカウントのクレジットウォレットから引かれます。

つまり API は匿名のモデルプロキシではありません。リクエストは Rivya アカウントに属し、そのアカウントが作成した API key を使い、API Credits で説明されている同じプロダクトレベルのクレジット境界に従います。

これはチームにとって有用です。Studio の実験と API 使用量が1つの運用モデルに留まるからです。モデルを手動でテストし、反復可能な部分を統合へ移しても、2つ目の請求レイヤーを作る必要はありません。

ファイルの位置づけ

一部のモデルはテキストだけで実行できます。別のモデルは参照画像、動画、音声ファイルを必要とします。

API 統合では、これらの参照素材は Files API を通すべきです。アップロードにより、対応するモデルパラメータへ渡せる管理済みファイルレコードが作られます。

実用ルールはシンプルです。

• モデルがテキストのみの入力を受け付けるなら、generation endpoint から始める
• モデルが参照メディアを必要とするなら、先にファイルをアップロードする
• モデルが画像添付付きの chat モデルなら、Chat API と file IDs を使う

ブラウザだけのアップロードフローや保存済み Studio セッションを前提に統合を設計しないでください。API には理由があって独自の公開ファイル境界があります。

Webhooks が役立つ場所

polling は最初の統合経路として最も簡単です。生成ジョブを送信し、公開タスク ID を保存し、成功または失敗するまで poll します。

統合がより本番に近くなると、Webhooks が役に立ちます。

• worker にすべてのジョブを polling させたくない
• アプリが生成完了時にレコードを更新する必要がある
• 安全に再試行できる署名付きイベントがほしい
• 失敗ジョブを明確な復旧経路へ移す必要がある

署名付きイベント契約は API Webhooks を使います。Webhook receiver は狭く保ってください。署名を検証し、重複イベントを処理し、secret 値をログに入れないようにします。

よい最初の API プロジェクト

最初の API プロジェクトは、小さく具体的であるのが通常は最適です。

例えば次です。

1. 設定で API key を作成する
2. モデルリストを呼び出す
3. 利用可能なモデルを1つ選ぶ
4. idempotency key 付きで1つの生成ジョブを送信する
5. status endpoint を polling する
6. 前後のクレジットを確認する
7. その後で Files API、Chat API、または Webhooks を追加する

この経路なら、最初のテストにすべての API 機能を混ぜ込まずに、動く統合を得られます。

API が間違った開始点になるとき

API は次の場合、おそらく正しい最初のステップではありません。

• チームがまだモデルファミリーを選んでいない
• 望む出力が実行ごとに変わっている
• プロンプトが手動の感覚とレビューに依存している
• 統合により、理解すべき人からクレジット使用量が見えにくくなる
• プロダクトには自動化より先に公開デモが必要

その場合は、Image、Video、Audio、Chat、または AI Models から始めます。経路が反復可能になったら、安定した部分を API へ移します。

次に進むページ

• 公開 API ハブとデバッガーは Developers を開いてください。
• 最初の安全なリクエストを行うには Rivya API Quickstart を読んでください。
• サーバーに key を置く前に API Authentication を読んでください。
• モデル ID を選ぶ前に API Models を読んでください。
• プロダクト境界がまだ不明なら Studio ではなく Rivya API を使うべきとき を読んでください。
• 画像、動画、音声、chat の完全な統合を計画しているなら、Rivya API でマルチモーダル AI ワークフローを構築する方法 を読んでください。