venice-responses

Venice Responses API（アルファ版）

POST /api/v1/responses は、Venice の OpenAI 互換 Responses エンドポイントです。単一の message.content 文字列ではなく、型付き出力配列を返します。これは、推論、メッセージ、ツール呼び出し、ウェブ検索イベントを分けて扱う必要があるエージェントに便利です。内部ではリクエストがチャット補完に変換されるため、モデルのサポート状況は venice-chat と同じです。

アルファ版。 仕様ではアルファ版と記載され（説明にもまだ「アルファテスターのみ」とあります）が、アクセス制限はすでに撤廃されています。任意の Bearer API キーまたは x402 ウォレットで呼び出せます。スキーマは今後変更される可能性があります。

使用する場面

• クライアントライブラリが OpenAI Responses 形式（type: "reasoning" | "message" | "function_call" | "web_search_call" を持つ output[]）を想定している場合。
• 推論、メッセージ、ツール呼び出しの出力を明確に分けたい場合。
• 型付きイベントを使った SSE ストリーミングが必要な場合。

それ以外の場合は venice-chat を使用してください。こちらは構造化出力、音声・動画・ファイル入力、E2EE、サンプリング制御、すべての venice_parameters フィールドに対応しています。

/chat/completions との違い

制限	詳細
ステートレス	何も保存されません。呼び出しごとに履歴全体を送信してください。previous_response_id、store、background は無視されます。
E2EE 非対応	E2EE 対応モデルは、venice_parameters.enable_e2ee: false（TEE のみのモード）を指定しないと 400 を返します。暗号化された推論には /chat/completions を使用してください。
テキストと画像入力のみ	input_text / input_image（および text / image_url の各パーツ）に対応しています。音声、動画、ファイルの各パーツには対応していません。
構造化出力非対応	text.format / response_format は破棄されます。/chat/completions を使用してください。
venice_parameters の一部のみ対応	character_slug、enable_e2ee、enable_web_search、enable_web_scraping、enable_web_citations、include_venice_system_prompt、include_search_results_in_stream に対応しています。その他のキー（strip_thinking_response、disable_thinking、enable_x_search、return_search_results_as_documents）は通知なく破棄されます。
モデル機能サフィックス非対応	model: "zai-org-glm-5-1:enable_web_search=on" はモデルを解決しますが、サフィックスは無視されます。
生成制御は限定的	temperature、top_p、max_output_tokens のみ対応しています。

認証

API の他のエンドポイントと同様に、Authorization: Bearer <key> または x402 ウォレット用の SIGN-IN-WITH-X: <SIWX> を使用します。venice-auth を参照してください。

最小限のリクエスト

curl https://api.venice.ai/api/v1/responses \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5-1",
    "input": "Explain why the sky is blue in one paragraph."
  }'

OpenAI SDK（Python）：

import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["VENICE_API_KEY"], base_url="https://api.venice.ai/api/v1")
resp = client.responses.create(model="zai-org-glm-5-1", input="Explain why the sky is blue.")
print(resp.output_text)

リクエストフィールド

フィールド	備考
model	必須です。モデル ID、特性、または互換性マッピングを指定します。
input	必須です。文字列、または入力項目（以下）の配列を指定します。
max_output_tokens	正の整数です。max_tokens にマッピングされます。モデルの model_spec.maxCompletionTokens を超える場合、上限が適用されるモデルでは 400 が返されます。
temperature（0～2）、top_p（0～1）	サンプリング用です。
reasoning.effort	none | minimal | low | medium | high | xhigh | max（モデルごとの対応状況：model_spec.capabilities.reasoningEffortOptions）。reasoning は null にできます。
reasoning.enabled	false にすると、対応モデルで推論が無効になり、推論ブロックも抑制されます。effort が設定されている場合は無視されます。
reasoning.summary	auto | concise | detailed。受け付けられますが、転送されません。
tools	Tools を参照してください。
tool_choice	"auto" | "none" | "required" | {"type":"function","function":{"name":"..."}}。関数ツールが残っていない場合は削除されます。
web_search	ブール値です。true にするとウェブ検索が強制的に有効になります（{"type":"web_search"} ツールと同じです）。
include	"reasoning.encrypted_content" のみ効果があります（プロバイダーから返された場合、推論ブロックに encrypted_content が追加されます）。
stream	ブール値です。型付きイベントによる SSE を使用します。
anon_user_id	任意のエンドユーザー ID：1～128 文字の印字可能な ASCII 文字で、`
fallbacks	最大 10 個の {model} エントリーを指定します。Claude Fable 5 用の Anthropic ベータ拒否フォールバックです。Anthropic への直接ルートでのみ転送されます。
venice_parameters	上記に記載されたサブセットです。例：{"character_slug":"alan-watts","enable_web_search":"auto"}。

リクエストボディではその他のフィールド（instructions、metadata、parallel_tool_calls、n、stop、seed、prompt_cache_key、store、previous_response_id、background、text、user）も受け付けられますが、エラーにはならないものの、推論には決して渡されません（user は値ごとにエラーバジェットを分割します）。instructions の代わりに、システム指示は input 配列に入れてください。

入力項目

項目	形式	処理
メッセージ	{role, content} または {type:"message", role, content}	role：user / assistant / system / developer（developer は system になります）。content は文字列またはパーツの配列です。
関数呼び出し	{type:"function_call", call_id, name, arguments}	アシスタントのツール呼び出しとして再生されます。
関数出力	{type:"function_call_output", call_id, output}	output は文字列、配列、オブジェクト、数値、ブール値、または null です。配列出力内の input_image パーツは、画像としてモデルに転送されます。
推論	{type:"reasoning", ...}	受け付けられますが、破棄されます — 推論はターン間で引き継がれません。
項目参照	{type:"item_reference", id}	受け付けられますが、破棄されます（参照する対象は保存されません）。

コンテンツパーツ：input_text、output_text（アシスタント出力を再生する場合）、および input_image。input_image.image_url は URL 文字列（OpenAI Responses 形式）、または {url, detail} にできます。detail（auto / low / high）はパーツに指定することもできます。type のないメッセージでは、Chat 形式の text および image_url パーツも受け付けられます。画像 URL には /chat/completions と同じ検証が適用されます（公開 URL、リダイレクトなし、64 px 以上）。失敗すると 400 が返されます。ビジョンモデルを使用してください。このエンドポイントでは、メッセージ内の画像について機能対応状況は確認されません（ビジョン非対応モデルの function_call_output 内にある画像は 400 を返します）。

ツール

ツール	効果
{"type":"function","function":{name, description, parameters, strict}}	関数呼び出し。フラットな OpenAI 形式の {"type":"function","name":...,"parameters":...} も受け付けます。このエンドポイントでは、チャットとは異なり事前チェックされないため、supportsFunctionCalling に対応したモデルを使用してください。
{"type":"web_search"}	Venice のウェブ検索を（auto ではなく）オンにします。search_context_size / user_location は受け付けますが、無視されます。
{"type":"x_search", ...}	supportsXSearch に対応したモデル（Grok）で、xAI ネイティブのウェブ検索と X 検索をオンにします。他のモデルでは無視されます。任意のフィルター：allowed_x_handles / excluded_x_handles（それぞれ 10 件以下）、from_date、to_date、enable_image_understanding、enable_video_understanding。
code_interpreter、file_search、computer_use_preview、その他	受け付けられますが、破棄されます。name を持つ未知のツールタイプは、関数ツールとして扱われます。

レスポンスの形式

{
  "id": "resp_chatcmpl-abc123",
  "object": "response",
  "created_at": 1735689600,
  "model": "zai-org-glm-5-1",
  "status": "completed",
  "output": [
    {"type": "reasoning", "id": "rs_1", "summary": ["I considered Rayleigh scattering..."]},
    {"type": "web_search_call", "id": "ws_1", "status": "completed"},
    {"type": "function_call", "id": "fc_1", "call_id": "call_abc", "name": "get_weather",
     "arguments": "{\"city\":\"Paris\"}", "status": "completed"},
    {"type": "message", "id": "msg_1", "status": "completed", "role": "assistant",
     "content": [{"type": "output_text", "text": "The sky is blue because... ^1^",
       "annotations": [{"type": "url_citation", "url": "https://example.com/rayleigh",
         "title": "Rayleigh scattering", "start_index": 27, "end_index": 30}]}]}
  ],
  "usage": {
    "input_tokens": 20,
    "input_tokens_details": {"cached_tokens": 8},
    "output_tokens": 80,
    "output_tokens_details": {"reasoning_tokens": 40},
    "total_tokens": 100
  }
}

• 非ストリーミング時の output の順序：reasoning → web_search_call → function_call（複数の場合あり）→ message。モデルがテキストを返さずツール呼び出しのみを返した場合、message ブロックは省略されます。
• status は completed または incomplete です。推論の前または途中で発生したエラーは HTTP エラーとして返されます（ストリーミングでは response.failed が使用されます）。
• 未完了のレスポンスでも、出力と使用量は保持されます。 生成が max_output_tokens またはコンテンツフィルターによって停止した場合、status: "incomplete"、incomplete_details: {"reason": "max_output_tokens" | "content_filter"} となり、message / function_call ブロックの status も "incomplete" になります。
• input_tokens_details はキャッシュされたトークンがゼロでない場合のみ表示されます。output_tokens_details はプロバイダーが推論トークンを報告した場合のみ表示されます。cost フィールドはありません（/chat/completions とは異なります）。

出力ブロックの種類

type	用途
reasoning	思考モデルによる推論です。summary[] にテキストが格納されます。encrypted_content は、include: ["reasoning.encrypted_content"] を指定して送信し、プロバイダーが暗号化された推論を返した場合のみ表示されます。これを input に含めて再送信しても効果はありません。
message	メインテキストです。content[].type === "output_text" で、annotations[] を含みます。
function_call	ツール呼び出しです。name、JSON 文字列の arguments、call_id が含まれます。同じ call_id を持つ function_call_output アイテムで応答してください。
web_search_call	Venice のウェブ検索が実行されたことを示すマーカーです。

url_citation アノテーションは、テキストに単一インデックスの ^n^ マーカーが含まれる場合のみ生成されます。アノテーションを取得するには、venice_parameters.enable_web_citations: true を設定してください。^1,3^ のような複数インデックスのマーカーにはアノテーションが付きません。

ストリーミング

stream: true の場合、イベントは event: <type> と data: {...} のペアで構成されます。ペイロードには type（イベント名と同じ）と、増加する sequence_number が含まれます。ただし、response.web_search.done のペイロードは例外で、type: "web_search_call"、id、status、results を含み、sequence_number はありません。一般的なフロー：

event: response.created                      # status: in_progress
event: response.web_search.done              # Venice-specific; only when search ran, carries results[{index,url,title,snippet}]
event: response.output_item.added            # item.type = reasoning
event: response.reasoning.delta
event: response.output_item.added            # item.type = message
event: response.content_part.added
event: response.output_text.delta            # repeated
event: response.output_item.added            # item.type = function_call
event: response.function_call_arguments.delta
event: response.output_item.done             # reasoning, then message (after content_part.done), then each function_call
event: response.completed                    # or response.incomplete, with the full response
data: [DONE]

• 上流でエラーが発生すると、response.failed（response.status: "failed"、response.error: {code, message}）の後に data: [DONE] が送信されます。
• 最終的な response.completed / response.incomplete ペイロードは、非ストリーミングのレスポンスと少し異なります。annotations は常に空で、function_call は message の後に続きます。
• include_search_results_in_stream はここでは効果がありません。検索結果は常に response.web_search.done で届きます。

エラー

ステータス	発生条件
400	無効なボディ、enable_e2ee: false を指定していない E2EE 対応モデル、無効な画像、モデルでサポートされていない reasoning.effort、コンテキストが長すぎる、max_output_tokens が上限を超えている
401	無効な API キーまたは SIWX サインイン。サブスクリプションの有料プランが必要なモデルも該当します
402	認証情報がまったくない（401 ではなく x402 の検出用ボディ）、残高不足、または API キーの利用額上限。x402：topUpInstructions と siwxChallenge を含む PAYMENT_REQUIRED ボディ、および PAYMENT-REQUIRED ヘッダー（venice-x402 を参照）
403	キーの modelPrivacy、リージョン、またはプロバイダーの制限によりモデルがブロックされている
404	不明なモデル
422	入力画像のコンテンツポリシー違反
429	レート制限
500 / 503	推論に失敗（上流の過負荷やタイムアウトもここでは 429 / 504 ではなく 500 として返されます。バックオフして再試行してください）／モデルがオフライン

仕様では x402 の 200 レスポンスに X-Balance-Remaining ヘッダーが記載されていますが、サーバーは現在これを設定しません。代わりに GET /x402/balance/{walletAddress} をポーリングしてください。venice-errors を参照してください。

移行に関する注意点（/chat/completions から）

• messages → input（同じ role/content オブジェクトを使用できます。システムプロンプトは role: "system" または "developer" の項目として指定します）。
• max_tokens → max_output_tokens、reasoning_effort → reasoning.effort。
• ツールの結果 → call_id をキーとする function_call_output 項目。
• venice_parameters.character_slug、enable_web_search、enable_web_citations、enable_web_scraping、include_venice_system_prompt → モデルサフィックスではなく、venice_parameters 内で渡します。
• enable_x_search → 代わりに {"type":"x_search"} ツールを追加します。
• strip_thinking_response / disable_thinking → reasoning.enabled: false を使用します。
• 構造化出力、オーディオ／動画／ファイル入力、seed / stop / n、logprobs、プロンプトキャッシュのルーティング、完全な E2EE → /chat/completions を引き続き使用します。

注意点

• 不明な character_slug はここでは拒否されません（chat では 404 が返されます）。リクエストはキャラクターなしで実行され、system メッセージ、Venice のシステムプロンプト、ウェブ検索も適用されません。まず GET /characters/{slug} でスラッグを検証してください（venice-characters を参照。Bearer キーのみ対応です。ウォレット呼び出し元は検証できないため、未知のスラッグに 404 を返す /chat/completions を使用してください）。
• input 内の推論項目は破棄されます。このエンドポイントではターンをまたいだ推論の引き継ぎはありません。
• tool_choice オブジェクトは {"type":"function","function":{"name":...}} である必要があります。フラットな {"type":"function","name":...} 形式は検証に失敗します。
• ステートレスです。previous_response_id は黙って無視されるため、履歴を省略するとコンテキストも黙って失われます。