venice-chat

Venice Chat Completions

POST /api/v1/chat/completions 是 Venice 的主要文本端点。它兼容 OpenAI，并额外提供仅适用于 Venice 的 venice_parameters 对象。身份验证方式为 Bearer API 密钥或 x402 钱包（SIGN-IN-WITH-X）；请参阅 venice-auth。

适用场景

• 需要生成大模型文本，可使用工具，也可不使用；可启用流式传输，也可不启用。
• 想向具备相应能力的模型提供多模态输入（图像、音频、视频、文档）。
• 想使用 Venice 专属功能：网络搜索、网页抓取、引文、E2EE、角色、xAI X/Twitter 搜索、思考控制。
• 需要为大型系统提示词或长文档启用提示词缓存。
• 需要结构化（json_schema）输出。

如需采用 OpenAI Responses 风格的结构（类型化的 output[] 块），请参阅 venice-responses。如需选择模型，请参阅 venice-text-routing。

最简请求

curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5-1",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}]
  }'

OpenAI SDK（Python）——Venice 专属字段放入 extra_body：

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.chat.completions.create(
    model="zai-org-glm-5-1",
    messages=[{"role": "user", "content": "Summarize today's AI news."}],
    extra_body={"venice_parameters": {"enable_web_search": "auto", "include_venice_system_prompt": False}},
)

响应结构采用标准的 OpenAI chat.completion 对象（id、object: "chat.completion"、created、model、choices[].message、choices[].finish_reason、usage），另外还包括：

• cost: {usd, diem} — 按请求所使用的计费货币拆分的费用（捆绑积分按 USD 计）。当响应没有输出 token 时为 0（此类响应不计费）。如果无法计算费用，则不返回此字段；目前，请求使用赚取的积分付款时也不返回此字段。
• venice_parameters — 实际生效的 Venice 设置，以及 web_search_citations[]（未执行搜索时为空数组）。
• 如果提供方报告了相关信息，则包含 usage.prompt_tokens_details.{cached_tokens, cache_creation_input_tokens} 和 usage.completion_tokens_details.reasoning_tokens。

choices[].finish_reason 的值为 stop、length、tool_calls 或 content_filter。content_filter 表示状态码为 200，但模型拒绝了请求或输出被截断（例如 Claude 拒绝）；它不是 422，因此在信任 message.content 之前，请先检查此值。有些提供方会在流传输中途拦截；此时流会以带内错误块（type: "content_filter_error"、code: "content_blocked_by_provider"）结束，后跟 [DONE]。

system_fingerprint 始终会被移除。设置 stream: true 时，响应采用 chat.completion.chunk 格式，以 SSE data: 行的形式返回。

请求体

顶层架构为严格模式：未知的顶层字段会返回 400。（少数兼容性别名会在验证前进行重写：input → messages、max_output_tokens → max_tokens、web_search: true|false → enable_web_search、promptCacheKey → prompt_cache_key。）

核心字段（兼容 OpenAI）

字段	说明
model	字符串 — 模型 ID、特征（例如 default、default_code）或兼容性映射。必填。允许使用功能后缀（见下文）。查找时也会兼容点号、下划线和空格（kimi k2.6 → kimi-k2-6），以及 venice- 前缀（适用于会劫持 claude-* 名称的 IDE）。
messages	system / developer / user / assistant / tool 消息数组。必填，至少 1 条。既没有 content 也没有 tool_calls 的助手消息会被静默丢弃。
temperature（0–2）、top_p（0–1）、top_k（整数 ≥ 0）、min_p（0–1）、min_temp、max_temp（0–2）	采样控制参数。部分模型会在 model_spec.constraints 中公布默认值。
repetition_penalty（≥ 0）、frequency_penalty、presence_penalty（−2..2）	重复控制参数
max_completion_tokens / max_tokens (已弃用)	整数。输出上限，包含推理 token。超过模型的 model_spec.maxCompletionTokens 时，对于设有 API 上限的模型会返回 400。max_tokens ≤ 0 时会被忽略；设置了 max_completion_tokens 时会忽略 max_tokens。
n	选项数量（默认为 1；所有选项都会计费）
seed	正整数
stop / stop_token_ids	字符串或 1–4 个字符串 / token ID 数组
stream、stream_options.include_usage	SSE 流式传输（即使未设置 include_usage，Venice 也会发送用量数据块 — 见“流式传输”）
response_format	{type:"json_schema", json_schema:{name, schema, strict}}（首选）、{type:"json_object"} 或 {type:"text"}
tools、tool_choice、parallel_tool_calls	函数调用
logprobs、top_logprobs（整数 ≥ 0）	对数概率
reasoning_effort / reasoning.effort	none | minimal | low | medium | high | xhigh | max。两者都设置时，以 reasoning_effort 为准。
reasoning.enabled	false 会在支持的模型上禁用推理。设置了 effort 时会被忽略。
reasoning.summary	auto | concise | detailed
prompt_cache_key	缓存路由提示。若省略，Venice 会为每个 API 用户生成稳定的键。
prompt_cache_retention	default | extended | 24h。对于支持的模型，extended 和 24h 会将保留时间延长至 24 小时。
verbosity / text.verbosity	low | medium | high | auto（两种位置均可接受）。非推理型 OpenAI 模型只接受 medium / auto（否则返回 400）。
anon_user_id	可选的最终用户标识符（见下文）
fallbacks	最多 10 个 {model} 条目。用于 Claude Fable 5 服务端拒绝回退的 Anthropic beta 参数。仅在直接 Anthropic 路由中转发，在其他情况下会被忽略。
include、metadata	为兼容 OpenAI 而接受；验证前会移除，且不会转发。
user、store	接受但会丢弃（兼容 OpenAI）。user 不是 anon_user_id 的别名。

anon_user_id — 用于标识你的最终用户；Venice 会在向上游归因请求时，将其与你的 Venice 用户 ID 结合。会去除首尾空格（空白值视为缺省）；长度为 1–128 个字符；仅限可打印 ASCII 字符（0x20–0x7E）；不得包含 ||。违反要求 → 400。/responses 也接受此字段。

能力门控（推理前返回 400）

你发送的内容	模型必须具备的能力（model_spec.capabilities）
image_url 部分	supportsVision
input_audio 部分	supportsAudioInput
video_url 部分	supportsVideoInput
tools、tool_choice、parallel_tool_calls: true	supportsFunctionCalling
除 text 以外的 response_format	supportsResponseSchema
logprobs: true 或任意 top_logprobs	supportsLogProbs

每次拒绝都会返回 400，对应字段的 issues[] 条目会说明原因；请查看 issues，而不只是顶层的 error。

OpenAI 推理模型（例如 openai-gpt-52）还会对 seed、stop、n ≠ 1 以及非零的 presence_penalty / frequency_penalty 返回 400（对应字段的 issues[] 条目内容为 "<field> is not supported by this model"）。

venice_parameters（仅限 Venice）

所有字段均为可选项。venice_parameters 中的未知键会被丢弃。

字段	类型	默认值	效果
character_slug	string	—	应用已发布的 Venice 角色（其页面上的“Public ID”）。未知 slug → 404。参见 venice-characters。
strip_thinking_response	bool	false	在推理模型上，从响应中移除推理内容（<think> 块和 reasoning_content）。
disable_thinking	bool	false	在支持的推理模型上禁用思考并移除推理内容。对于无法关闭推理的模型，推理仍会运行（部分模型会降至最低推理强度），但会从响应中移除；这些推理令牌仍可能计费。
enable_e2ee	bool	true	在支持 E2EE 的模型上，如果存在 E2EE 标头，则使用 E2EE。false 会强制使用仅 TEE 模式。
enable_web_search	"off" / "auto" / "on"	"off"	Venice 网络搜索。on 始终搜索；auto 由分类器决定。
enable_web_scraping	bool	false	抓取最新用户消息中找到的 URL。找到 URL 时，本次请求会以抓取替代网络搜索。
enable_web_citations	bool	false	要求模型以 ^1^ / ^1,3^ 的形式引用来源。
include_search_results_in_stream	bool	false	实验性功能。仅限流式传输：在流结束时、data: [DONE] 之前，发出一个携带 venice_parameters.web_search_citations 的 choices: [] 分块。
return_search_results_as_documents	bool	—	同时将搜索结果作为合成工具调用提供（参见 Web 搜索）。
include_venice_system_prompt	bool	true	在你的系统提示词前添加 Venice 的系统提示词。设为 false 可完全自行控制。
enable_x_search	bool	false	在支持 supportsXSearch 的模型（Grok）上启用 xAI 原生网络 + X 搜索。在其他模型上会忽略。按搜索次数计费（约 $0.01）。

模型功能后缀

某些 venice_parameters 可以设置在 model 字符串上——当客户端（OpenAI SDK、LangChain、IDE）无法发送 venice_parameters 时，这很有用：

<model-id>:<key>=<value>[&<key>=<value>…]

值会进行 URL 解码；布尔值为 true / false。后缀会覆盖 venice_parameters 中的同名键。支持的键（必须完全匹配）：

键	值	映射到
enable_web_search	on / off / auto	venice_parameters.enable_web_search
enable_web_citations	true / false	venice_parameters.enable_web_citations
enable_web_scraping	true / false	venice_parameters.enable_web_scraping
include_venice_system_prompt	true / false	venice_parameters.include_venice_system_prompt
include_search_results_in_stream	true / false	venice_parameters.include_search_results_in_stream
return_search_results_as_documents	true / false	venice_parameters.return_search_results_as_documents
character_slug	字符串	venice_parameters.character_slug
strip_thinking_response	true / false	venice_parameters.strip_thinking_response
disable_thinking	true / false	venice_parameters.disable_thinking

未知键会被静默忽略。enable_e2ee 和 enable_x_search 不是后缀键。后缀仅适用于 /chat/completions——/responses 会解析模型，但忽略后缀。

zai-org-glm-5-1:enable_web_search=on
kimi-k2-6:strip_thinking_response=true&enable_web_search=auto
zai-org-glm-5-1:character_slug=alan-watts

消息和模态

messages[].content 是字符串或由带类型的部分组成的数组。角色：user、assistant、tool、system、developer。只有 user 消息可以包含图像／音频／视频／文件部分；system／developer／assistant 的数组内容只能是文本。Anthropic 风格的 tool_use／tool_result 块和 Cursor 风格的 {type:"image"} 部分会自动转换。

每条消息的上限：10 个 image_url、5 个 input_audio、3 个 video_url、5 个 file 部分。每个请求的上限：总共 3 个 video_url 部分。

图像（image_url）

{
  "model": "kimi-k2-6",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ]
  }]
}

• url 必须是公开的 http(s) URL 或 data:image/...;base64,... URL（上方的 example.com 占位符无法通过验证——请替换为真实图像）。远程 URL 会被抓取一次以进行验证：不接受重定向，正文必须 ≤ 25 MB，Content-Type 必须是 PNG、JPEG、WebP、HEIF/HEIC 或 AVIF，且图像必须能够解码，并且每边至少为 64 px（data URL 也会进行相同的解码和尺寸检查）。失败时会返回 400 "Supplied image did not pass validation checks."
• supportsMultipleImages: true 的模型会保留整个对话中的图像（maxImages 会公布模型的每请求上限；Venice 本身会强制执行每条消息 10 个的上限）。单图视觉模型只保留最后一条包含图像的消息中的图像；更早的图像会被移除。

音频（input_audio）

{"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}}

format：wav（默认）、mp3、aiff、aac、ogg、flac、m4a、pcm16、pcm24。音频必须是内联 base64——不支持 URL。

视频（video_url）

{"type": "video_url", "video_url": {"url": "https://www.youtube.com/watch?v=..."}}

• 接受 YouTube 观看／分享／嵌入链接，且不会预先抓取（是否受支持因提供方而异）。
• data:video/...;base64,... URL 必须声明 video/mp4、video/mpeg、video/quicktime、video/mov 或 video/webm。
• 其他远程 URL 必须返回 2xx，且不得重定向，并且 Content-Type 必须是上述类型之一。失败时会返回 400 "Supplied video did not pass validation checks."
• 请求中的 video_url 部分超过 3 个时会返回 400（在抓取任何 URL 之前进行检查）。

文档（file）

{"type": "file", "file": {"file_data": "data:application/pdf;base64,JVBERi0...", "filename": "report.pdf"}}

file_data 可以是 data URL 或公开 URL。PDF、EPUB、DOCX、PPTX、XLSX、XLS、纯文本、Markdown、CSV、JSON 和大多数源代码文件都会在服务端提取为文本（因此任何文本模型都可以使用）；图像文件会转换为 image_url 部分。无法提取的文件会变成内联的 [Error processing file …] 文本部分，而不会导致请求错误。E2EE 请求不允许使用。

提示词缓存（cache_control）

任何内容部分都可以携带 {"cache_control": {"type": "ephemeral"}} 或 {"type": "ephemeral", "ttl": "1h"}。对于需要显式标记的模型（Claude），这些标记很重要；其他模型会根据前缀匹配自动缓存。这些模型每个请求最多允许 4 个断点；只有在你的标记留有空位时，Venice 才会为系统提示词和对话历史添加自己的断点。搭配稳定的 prompt_cache_key，可确保路由一致。缓存读取 / 写入价格因模型而异（model_spec.pricing.cache_input / cache_write）；命中情况会报告在 usage.prompt_tokens_details 中。

工具与函数调用

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
      "strict": true
    }
  }],
  "tool_choice": "auto"
}

• tool_choice："auto"、"required"、"none"，或 {"type":"function","function":{"name":"get_weather"}}。{"type":"auto" | "none" | "required"} 会规范化为字符串形式。
• parallel_tool_calls 默认值为 true——请准备好在回复前执行多次调用。
• 每次调用都回复一条 {"role":"tool","tool_call_id":"...","content":"..."} 消息，然后再次调用。
• 扁平格式（{type, name, parameters}）和 Anthropic 格式（{name, input_schema}）的工具定义会转换为嵌套格式。
• 当消息包含工具调用时，Venice 会报告 finish_reason: "tool_calls" 而不是 stop（被 length 截断时仍为 length）。
• 架构也接受 {"type":"web_search"} / {"type":"x_search"} 工具条目，但它们不会启用 Venice 搜索或 xAI X 搜索。请改用 venice_parameters.enable_web_search / enable_x_search。

推理模型

{
  "model": "zai-org-glm-5-1",
  "reasoning": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Prove there are infinitely many primes."}]
}

• 推理内容会出现在 message.reasoning_content 中（流式传输时为 delta.reasoning_content）；content 中的 <think> 标签会被移除。部分提供商会返回加密或摘要后的推理内容。
• 支持的推理强度值因模型而异：请查看 model_spec.capabilities.supportsReasoningEffort、reasoningEffortOptions 和 defaultReasoningEffort。对于大多数 Claude 模型和 OpenAI GPT 模型，不在 reasoningEffortOptions 中的值会导致 400（none 始终可用，作为 Venice 级别的关闭开关；在 OpenAI 模型上，minimal 也受支持，并映射到最低支持级别）。其他模型不会进行预验证，因此请使用 reasoningEffortOptions 中的值。
• 若要关闭思考，优先使用 reasoning: {"enabled": false} 或 venice_parameters.disable_thinking: true——这两种方式在强制推理模型上也能平稳降级。reasoning_effort: "none" 也会在模型允许时关闭思考，但部分强制推理模型会拒绝此设置；建议优先使用上述两个开关。
• 部分模型会在助手消息中返回 reasoning_details[]（通过原生传输的 Gemini 会返回 thought_signature）。请在下一轮中原样传回这些内容，尤其是在工具调用循环中，以保留思考签名。
• 推理令牌计入 max_completion_tokens，并按输出计费。

结构化输出（response_format）

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"name": {"type": "string"}, "age": {"type": "number"}},
        "required": ["name", "age"],
        "additionalProperties": false
      }
    }
  }
}

将 JSON Schema 放在 json_schema.schema 下（OpenAI 格式）——Claude、Gemini 和 Grok 模型只会从该位置读取它。Claude 模型已弃用并忽略 json_object。需要 supportsResponseSchema。

E2EE（端到端加密）

对于 supportsE2EE: true 的模型（e2ee-* ID），请遵循 TEE 与 E2EE 指南：

1. GET /api/v1/tee/attestation?model=<id>&nonce=<64 hex chars>（无需身份验证，每个 IP 每分钟 10 次请求）。验证响应并获取模型的公钥。
2. 为每个会话生成一对 secp256k1 密钥。使用 ECDH → HKDF-SHA256 → AES-256-GCM 加密每条 user 和 system 消息。
3. 使用 X-Venice-TEE-Client-Pub-Key 和 X-Venice-TEE-Model-Pub-Key（secp256k1 十六进制密钥）、X-Venice-TEE-Signing-Algo: ecdsa，以及 stream: true 发送请求（指南要求使用流式传输）。格式错误的标头会返回 400 和 {"error":{"message":"Invalid E2EE headers: …","type":"invalid_request_error"}}。
4. 使用你的私钥解密流式内容。

对于 E2EE 请求，Venice 不会注入任何内容：没有 Venice 系统提示词、角色、网页搜索或抓取内容。file 部分会返回 400。指南还列出函数调用为不支持的功能。未提供 E2EE 标头（或设置 enable_e2ee: false）时，同一模型会以仅 TEE 模式运行。TEE 响应包含 X-Venice-TEE: true 和 X-Venice-TEE-Provider。/responses 不支持 E2EE。

流式传输

{"stream": true}

• 使用 text/event-stream，每个事件包含一个 data: {chat.completion.chunk}，并以 data: [DONE] 结束。
• Venice 会向模型请求用量信息，并在 [DONE] 之前通过包含 usage（和 cost）的 choices: [] 数据块发送，无论 stream_options.include_usage 的设置为何。内容数据块中不会重复发送用量信息。
• 如果上游在发送标头后发生故障，你会收到一个内嵌的 data: {"error": {...}} 数据块（例如，包含 retry_after 的 code: "model_overloaded"、upstream_error 或 content_blocked_by_provider），随后是 [DONE]。
• 除非设置 include_search_results_in_stream: true，否则流中不会包含网页搜索引用。设置后，流末尾、[DONE] 之前会收到一个包含 venice_parameters.web_search_citations 的 choices: [] 数据块。
• 设置 return_search_results_as_documents: true 后，合成的 web_search_call 工具调用（参见网页搜索）会在内容之前作为 delta.tool_calls 数据块发送。

网页搜索

• 非流式响应会包含 venice_parameters.web_search_citations[]，其中包含 url、title、content（摘要）和 date。添加 enable_web_citations: true 可在文本中获取 ^n^ 标记。
• 对于 E2EE 请求、最后一条用户消息包含图片，或抓取功能在该消息中发现 URL 时，将跳过搜索。
• 设置 return_search_results_as_documents: true 会添加一个合成工具调用 {id:"web_search_call", type:"function", function:{name:"web_search", arguments:"{\"documents\":[{id,title,url,snippet,published_at}]}"}}，并将 finish_reason 设为 "tool_calls"。不要尝试执行此调用。
• 计费：每个搜索增强请求 $0.01，每个抓取的 URL $0.01，每次 xAI X 搜索 $0.01。

错误处理详情

状态	适用情况
400	请求体无效（error: "Invalid request parameters"，各字段的原因见 issues[]）、能力不支持、图像或视频无效、部分数量过多、超出上下文长度、超出令牌上限、E2EE 标头错误
401	API 密钥或 SIWX 登录无效；也可能是模型需要付费订阅
402	完全没有凭据（x402 发现响应体，不是 401）、余额不足或 API 密钥支出限额。x402 余额不足时，响应体包含 code: "PAYMENT_REQUIRED"，并附带 topUpInstructions 和 siwxChallenge，同时带有 PAYMENT-REQUIRED 标头（venice-x402）
403	API 密钥的 modelPrivacy 不允许使用该模型、模型受地区限制，或提供商限制
404	未知模型（通常会附带“Did you mean”提示）或 character_slug
413	负载过大
422	违反内容政策（Venice 或提供商）
429	超出速率限制（"Rate limit exceeded" 或错误预算提示），或模型过载（出现 "The model is currently overloaded…"，并带有 Retry-After 标头）。两种情况都会带有 x-ratelimit-* 标头，因此可根据 Retry-After 和提示信息加以区分
500 / 503 / 504	推理失败 / 模型离线 / 上游超时

有关错误格式和重试策略，请参阅 venice-errors。

常见注意事项

• max_tokens 已弃用，请改用 max_completion_tokens，并确保不超过 model_spec.maxCompletionTokens。
• 未知顶层字段会被拒绝（400）；未知的 venice_parameters 键会被静默丢弃。
• 图像和视频 URL 必须可公开访问，且不能经过重定向。会重定向的 S3 签名 URL 或 localhost URL 均会失败。
• 音频不能使用 URL，必须始终采用 base64。
• 单图像视觉模型每轮都会丢弃较早的图像；请将图像放在用户的最后一条消息中。
• 在多轮工具循环中，原样传递 reasoning_details / thought_signature。
• character_slug 会将角色的系统提示词置于你的提示词之前。除非角色使用自定义系统提示词，或你设置了 include_venice_system_prompt: false，否则 Venice 自带的提示词仍会包含在内。
• web_search / x_search 工具条目并非 Venice 搜索，请使用 venice_parameters。
• OpenAI 推理模型不接受 seed、stop、n > 1 和非零惩罚值。