venice-responses

Venice Responses API（Alpha）

POST /api/v1/responses 是 Venice 兼容 OpenAI 的 Responses 端点。它返回一个类型化输出数组，而不是单个 message.content 字符串——这对需要区分推理、消息、工具调用和网页搜索事件的 Agent 很有用。请求会在内部转换为聊天补全，因此模型支持情况与 venice-chat 一致。

Alpha。 规范将其标记为 Alpha（描述仍写着“仅限 Alpha 测试者使用”），但现在访问权限已不再受限：任何 Bearer API 密钥或 x402 钱包都可以调用。Schema 仍可能发生变化。

适用场景

• 客户端库需要 OpenAI Responses 格式（output[]，其中 type: "reasoning" | "message" | "function_call" | "web_search_call"）。
• 你希望将推理、消息和工具调用输出清晰分开。
• 你希望使用带类型事件的 SSE 流式传输。

其他情况请使用 venice-chat——它支持结构化输出、音频／视频／文件输入、E2EE、采样控制以及所有 venice_parameters 字段。

相较于 /chat/completions 的限制

限制	详情
无状态	不会存储任何内容。每次调用都要发送完整历史记录。previous_response_id、store、background 均会被忽略。
不支持 E2EE	支持 E2EE 的模型会返回 400，除非设置 venice_parameters.enable_e2ee: false（仅 TEE 模式）。如需加密推理，请使用 /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 其余部分相同——x402 钱包可使用 Authorization: Bearer <key> 或 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	参见工具。
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 Beta 拒绝回退；仅在直连 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 仍会按各个值拆分错误预算）。请将系统指令放在 input 数组中，而不是 instructions 中。

输入项

项目	格式	处理方式
消息	{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 相同的验证规则（公开、无重定向、≥ 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[] 保存文本；只有在你发送 include: ["reasoning.encrypted_content"] 且提供商返回了加密推理内容时，才会出现 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 网页搜索已运行的标记。

仅当文本包含单索引 ^n^ 标记时，才会生成 url_citation 注释 — 设置 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 始终为空，函数调用排在 message 之后。
• include_search_results_in_stream 在此处无效；搜索结果始终通过 response.web_search.done 返回。

错误

状态	发生条件
400	请求正文无效；支持 E2EE 的模型未设置 enable_e2ee: false；图像无效；模型不支持 reasoning.effort；上下文过长；max_output_tokens 超出上限
401	API 密钥或 SIWX 登录无效；或者使用了要求付费订阅的模型
402	完全没有凭据（x402 发现响应正文——不是 401）；余额不足；或者 API 密钥支出达到上限。x402：返回包含 topUpInstructions + siwxChallenge 的 PAYMENT_REQUIRED 正文，以及 PAYMENT-REQUIRED 标头（见 venice-x402）
403	模型因密钥的 modelPrivacy、区域或提供商限制而被屏蔽
404	未知模型
422	输入图像违反内容政策
429	请求频率受限
500 / 503	推理失败（上游过载和超时也会在此处返回 500，而非 429 / 504；请采用退避策略重试）/ 模型离线

规范列出了 x402 200 响应中的 X-Balance-Remaining 标头，但服务器目前不会设置该标头；请改为轮询 GET /x402/balance/{walletAddress}。见 venice-errors。

迁移说明（从 /chat/completions 迁移）

• messages → input（相同的 role/content 对象可直接使用；system 提示词应作为 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} 验证 slug（venice-characters；仅限 Bearer 密钥——钱包调用方无法执行此操作，应使用 /chat/completions，该端点会对未知 slug 返回 404）。
• input 中的推理项会被丢弃；此端点不会跨轮次保留推理内容。
• tool_choice 对象必须采用 {"type":"function","function":{"name":...}} 格式；扁平格式 {"type":"function","name":...} 会导致验证失败。
• 无状态：previous_response_id 会被静默忽略，因此省略历史记录会导致上下文静默丢失。