Rivya Chat API を使い、非ストリーミングまたは SSE のターン、API 作成セッション、file_id 画像添付、token ベースのクレジット精算を扱います。

完全な非ストリーミングのチャット応答を 1 回取得するには POST /api/v1/chat/completions を使い、Server-Sent Events には POST /api/v1/chat/completions/stream を使います。

Chat API はセッションベースです。新しい API チャットセッションを開始するには session_id を省略します。返された session_id を渡すと、同じ API 作成セッションを続行できます。

現在の範囲

Chat API v1 は次に対応しています。

非ストリーミングの assistant 応答
text/event-stream を使う SSE ストリーミング
API 作成のチャットセッション
アカウントクレジットの予約と、最終的な token ベースの精算
選択したモデルが対応している場合の web search、reasoning effort、thought mode
Files API の file_id 値を使う画像添付

Chat API v1 は次に対応していません。

ユーザー指定の生の messages 履歴
Studio 専用チャットセッションの続行
任意の外部添付 URL
Chat webhook events

必要なスコープ

次のスコープを含む API キーを使います。

chat:create
chat:read

Settings で新しく作成したキーには、デフォルトで両方のスコープが含まれます。古いキーは、Chat API を呼び出す前に再作成が必要になる場合があります。

Chat Completion を作成する

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

応答:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "gpt-5-2-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

Chat Completion をストリーミングする

サーバー側で assistant の delta を到着順に受け取りたい場合は、POST /api/v1/chat/completions/stream を使います。

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

ストリーミング応答は Content-Type: text/event-stream; charset=utf-8 を使います。

イベント:

イベント	意味
`session.created`	API キー、モデル、セッション、添付、rate limit、クレジット予約のチェックに通過しました。
`message.delta`	assistant メッセージの表示用 delta です。まだ確定済みメッセージではありません。
`message.completed`	assistant メッセージが API 作成セッションへ確定されました。
`usage.completed`	token 使用量と最終クレジットが精算されました。
`heartbeat`	長い待機中の keepalive イベントです。
`error`	ストリーミング開始後に失敗した場合の Public API エラーエンベロープです。
`done`	ストリームが正常に完了しました。

ストリーム例:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

最初の SSE イベント後にエラーが起きた場合、ストリームは event: error を送信してから閉じます。

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

完了前にクライアントが切断した場合、Rivya は可能な限り進行中の生成ストリームを停止します。部分的な delta は最終 assistant メッセージとして保存されません。サーバーがすでに message.completed を確定している場合、最終結果は後から GET /api/v1/chat/sessions/{sessionId} で読み取れます。

セッションを続行する

返された session_id を使います。

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

そのセッションは同じ Rivya アカウントに属し、Public API によって作成されている必要があります。Studio 専用のチャットセッションは、Chat API では返されず、続行もされません。

画像添付

Chat の添付は外部 URL ではなく、Files API レコードを使います。

POST /api/v1/files で画像をアップロードします。
返された id を attachments[].file_id として使います。

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

ファイルは同じアカウントに属し、kind: "image" で、利用可能な状態である必要があります。画像添付に対応していないモデルは chat_attachment_not_supported を返します。

オプション制御

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

制御項目の対応状況はモデルによって異なります。UI に制御を公開する前に、/api/v1/models を読み取り、chat_capabilities を確認してください。

セッション一覧

chat:read を含むキーで GET /api/v1/chat/sessions を使います。

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

これは API 作成セッションのみを返します。

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

セッションを取得する

API 作成セッション 1 件と、その確定済みメッセージを読み取るには GET /api/v1/chat/sessions/{sessionId} を使います。

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

応答には、確定済みの user と assistant のメッセージが含まれます。内部 provider フィールドは公開されません。

冪等性

本番環境のすべての POST /api/v1/chat/completions と POST /api/v1/chat/completions/stream リクエストには、Idempotency-Key を使ってください。

同じキーと同じ body でリトライした場合、Rivya は別のメッセージを作成したり再度クレジットを消費したりせず、保存済みの応答を返せます。同じキーを異なる入力で再利用した場合、API は idempotency_conflict を返します。

ストリーミングのリトライでは、Rivya は過去の token delta を再生しません。完了済みのリプレイは、session.created、message.completed、usage.completed、done を含む最小の SSE シーケンスを返します。

よくあるエラー

コード	意味
`chat_model_not_supported`	選択したモデルは Chat API で利用できません。
`chat_session_conflict`	このリクエストではそのセッションを使用できません。
`chat_attachment_not_supported`	添付が見つからない、アカウント所有ではない、画像ではない、またはモデルが対応していません。
`insufficient_credits`	このターンに必要なクレジットがアカウントにありません。
`idempotency_conflict`	冪等性キーが異なる入力で再利用されました。

Chat API ガイド