ストリーミングプロトコル
対象:
/v1/chat/completions、/v1/responses、/v1/messages、/v1/jobs/:id/events
Nexith のストリーミングレスポンスはすべて text/event-stream(SSE)です。テキスト生成は OpenAI 互換の
chat.completion.chunk フレームを使用し、画像ジョブはジョブイベントフレームを使用します。また、呼び出し元が対応する nexith_* 拡張を
明示的に有効にした場合にのみ現れる、少数の nexith.* サイドチャネルフレームがあります。
1. テキストストリーム(Chat Completions)#
リクエスト#
{
"model": "nexith-core",
"messages": [{"role": "user", "content": "写一首短诗"}],
"stream": true,
"stream_options": {"include_usage": true}
}フレーム形式#
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1795055220,"model":"nexith-core","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":34,"total_tokens":46}}
data: [DONE]要点:
data: <json>\n\nで送信し、最後は固定でdata: [DONE]です。stream_options.include_usage=trueの場合、[DONE]の前にchoices: []+usageのフレームが 1 つあります。 課金はこのフレームを基準にします。指定しない場合は使用量フレームがありません(OpenAI の旧動作)。- ツール呼び出しは
delta.tool_callsとして差分配信され、連結ルールは OpenAI と同一です。 - 接続はサーバーがキープアライブします(SSE comment ハートビート)。プロキシのタイムアウトは通常 300s です。
エラー#
- 最初の token より前の失敗:通常の HTTP エラー(4xx/5xx + JSON body)を返し、先に 200 を送ることはありません。
- 出力開始後の失敗:ステータスコードは変更できないため、ストリーム内でエラーオブジェクトを 1 フレーム送ってから終了します。クライアントは 受信済みの内容を不完全として扱ってください。
2. サイドチャネルフレーム(Nexith 拡張)#
リクエストに対応するスイッチが含まれる場合にのみ現れます。純粋な OpenAI クライアントはこれらのフレームを受け取りません。
nexith.sources(Web 検索のソース)#
回答の最初のフレームより前に送信され、フロントエンドが引用カードを先に描画できるようにします:
{
"object": "nexith.sources",
"sources": [
{"title": "…", "url": "https://…", "content": "摘要片段"}
]
}nexith.step(深掘り調査の進捗)#
深掘り調査の各段階(計画、検索、取得、圧縮)をフレーム単位でリプレイし、nexith.sources より前に位置します:
{"object": "nexith.step", "label": "检索", "model": "…", "content": "…", "items": [...]}nexith.image_request(画像生成意図)#
リクエストに nexith_detect_media: true が含まれ、L1 が画像生成意図と判定した場合、ゲートウェイはテキストストリームに入らず、
非ストリーミング JSON を直接返します:
{
"object": "nexith.image_request",
"capability": "image.generate",
"target_model": "nexith-image",
"original_prompt": "画一只小猫",
"enhanced_prompt": "A cute kitten, …",
"size": "1024x1024"
}フロントエンドは受け取ったら POST /v1/images/generations を呼び出して非同期ジョブを送信してください。画像編集意図の場合は
nexith.image_edit_request に対応します(参照画像情報が追加で含まれます)。
nexith.routing_decision(Responses アダプター層)#
/v1/responses は、呼び出し元にケイパビリティの補足が必要な場合にこの構造を返すことがあります(status=requires_capability)。
これは「この種のリクエストにどのケイパビリティティアが必要か」をクライアントに伝えるためのもので、テキスト回答を偽装するものではありません。
3. 非ストリーミングレスポンスの nexith オブジェクト#
非ストリーミングの Chat Completions レスポンスボディには、トップレベルの nexith オブジェクトが含まれる場合があります(同様に拡張が有効な場合のみ):
{
"id": "chatcmpl-...",
"object": "chat.completion",
"choices": [...],
"usage": {...},
"nexith": {
"memory": [{"id": "...", "content": "...", "score": 0.83}],
"sources": [{"title": "...", "url": "...", "content": "..."}],
"steps": [{"label": "...", "model": "...", "content": "..."}]
}
}フィールドはすべて任意です:return_memory → memory、nexith_web_search → sources、
nexith_deep_research → steps。
4. ジョブイベントストリーム(Jobs SSE)#
GET /v1/jobs/:id/events はジョブイベントストリームを返します。フレーム形式はテキストストリームとは異なります:
data: {"event":"queued","payload":{},"ts":"2026-11-19T02:00:00Z"}
data: {"event":"started","payload":{},"ts":"..."}
data: {"event":"completed","payload":{},"ts":"..."}- イベント種別:
queued/started/error/completed/failed/cancelled。 - 各接続はイベント 0 からリプレイされ、クライアントは再接続するだけですべての履歴イベントを補完できます。
- サーバーは 15 秒ごとに SSE comment ハートビートを送信し、プロキシのアイドル切断を防ぎます。
error/failedのpayload.errorは不透明な固定文言で、アップストリームのモデル名や内部エラーの原文を含みません。completed/failed/cancelledを受信すると、サーバーはストリームを終了します。
5. クライアントへの推奨#
- 公式 SDK を使う場合は SSE を手動解析せず、
stream=trueを直接使用してください。 - 自前実装のクライアントでは、chunk 境界をまたぐ不完全なフレーム、
[DONE]の終了、空行のハートビートを処理する必要があります。 - 切断時の再試行:テキストストリームにはレジューム機能がなく、再試行は新たな課金リクエストを発生させます。ジョブストリームは安全に再接続できます。