> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-mintlify-6ce01df5.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 简介 > Venice API 的参考文档 Venice API 提供基于 HTTP 的 REST 和流式接口，用于构建使用无审查模型与私有推理的 AI 应用。您可以创建文本生成、图像生成、嵌入向量等内容，所有这些都不受限制性内容政策的约束。集成示例和 SDK 可在[文档](/overview/getting-started)中查看。我们的 API 参考也可作为 [OpenAPI YAML 规范](https://api.venice.ai/doc/api/swagger.yaml)使用。 ## 身份验证 Venice API 使用 API 密钥进行身份验证。在您的 [API 设置](https://venice.ai/settings/api)中创建和管理您的 API 密钥。 所有 API 请求都需要 HTTP Bearer 身份验证： ``` Authorization: Bearer VENICE_API_KEY ``` 您的 API 密钥是机密信息。请勿共享或在任何客户端代码中暴露它。 ## OpenAI 兼容性 Venice 的 API 实现了 OpenAI API 规范，确保与现有的 OpenAI 客户端和工具兼容。这使您可以使用熟悉的 OpenAI 接口与 Venice 集成，同时访问 Venice 独有的功能和无审查模型。 ### 设置 将您的客户端配置为使用 Venice 的 base URL（`https://api.venice.ai/api/v1`）并发起首个请求： ```bash curl theme={"system"} curl https://api.venice.ai/api/v1/chat/completions \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "venice-uncensored", "messages": [{"role": "user", "content": "Hello!"}] }' ``` ```javascript JavaScript theme={"system"} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.VENICE_API_KEY, baseURL: "https://api.venice.ai/api/v1", }); const response = await client.chat.completions.create({ model: "venice-uncensored", messages: [{ role: "user", content: "Hello!" }] }); console.log(response.choices[0].message.content); ``` ```python Python theme={"system"} import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("VENICE_API_KEY"), base_url="https://api.venice.ai/api/v1" ) response = client.chat.completions.create( model="venice-uncensored", messages=[{"role": "user", "content": "Hello!"}] ) print(response.choices[0].message.content) ``` ## Venice 专有功能 ### 系统 prompt Venice 提供默认的系统 prompt，旨在确保模型响应无审查且自然。您有两种处理系统 prompt 的方式： 1. **默认行为**：您的系统 prompt 会附加到 Venice 的默认值之后 2. **自定义行为**：完全禁用 Venice 的系统 prompt #### 禁用 Venice 系统 prompt 使用 `venice_parameters` 选项移除 Venice 的默认系统 prompt： ```bash curl theme={"system"} curl https://api.venice.ai/api/v1/chat/completions \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "venice-uncensored", "messages": [ {"role": "system", "content": "Your custom system prompt"}, {"role": "user", "content": "Why is the sky blue?"} ], "venice_parameters": { "include_venice_system_prompt": false } }' ``` ```javascript JavaScript theme={"system"} const completion = await client.chat.completions.create({ model: "venice-uncensored", messages: [ { role: "system", content: "Your custom system prompt", }, { role: "user", content: "Why is the sky blue?", }, ], venice_parameters: { include_venice_system_prompt: false, }, }); ``` ```python Python theme={"system"} response = client.chat.completions.create( model="venice-uncensored", messages=[ {"role": "system", "content": "Your custom system prompt"}, {"role": "user", "content": "Why is the sky blue?"} ], extra_body={ "venice_parameters": { "include_venice_system_prompt": False } } ) ``` ### Venice 参数 `venice_parameters` 对象允许您访问标准 OpenAI API 中不可用的 Venice 专有功能： | 参数 | 类型 | 说明 | 默认值 | | ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `character_slug` | string | 公共 Venice 角色的角色 slug（在已发布的角色页面上以"Public ID"形式可发现） | - | | `strip_thinking_response` | boolean | 从响应中剥离 `` 块（适用于使用旧版 `` 标签格式的模型）。请参阅[推理模型](/guides/features/reasoning-models)。 | `false` | | `disable_thinking` | boolean | 在支持的推理模型上，禁用思考过程并从响应中剥离 `` 块 | `false` | | `enable_web_search` | string | 为此请求启用网页搜索（`off`、`on`、`auto` - auto 由模型自行决定是否启用）
会产生额外的按用量计费，请参阅[定价](/overview/pricing#web-search-and-scraping)。 | `off` | | `enable_web_scraping` | boolean | 启用对用户消息中检测到的最多 5 个 URL 的网页抓取。抓取的内容会增强响应并绕过网页搜索。仅对成功抓取的 URL 计费。
会产生额外的按用量计费，请参阅[定价](/overview/pricing#web-search-and-scraping)。 | `false` | | `enable_x_search` | boolean | 为支持的 Grok 模型（如 `grok-4-20-beta`）启用 xAI 原生搜索（web + X/Twitter）。通过使用 xAI 的搜索基础设施提供更高质量的搜索结果。启用后，Venice 标准的网页搜索会被绕过。
会产生额外的按用量计费，请参阅[定价](/overview/pricing#web-search-and-scraping)。 | `false` | | `enable_web_citations` | boolean | 启用网页搜索时，请求 LLM 使用 `[REF]0[/REF]` 格式引用其来源 | `false` | | `include_search_results_in_stream` | boolean | 实验性：将搜索结果作为首个发出的 chunk 包含在流中 | `false` | | `return_search_results_as_documents` | boolean | 将搜索结果通过名为 `venice_web_search_documents` 的 OpenAI 兼容 tool call 暴露，用于 LangChain 集成 | `false` | | `include_venice_system_prompt` | boolean | 是否在指定的系统 prompt 之外包含 Venice 的默认系统 prompt | `true` | 这些参数也可以作为附加在模型名称之后的模型后缀指定（例如 `zai-org-glm-5:enable_web_search=auto`）。详细信息请参阅[模型功能后缀](/api-reference/endpoint/chat/model_feature_suffix)。 ### Prompt 缓存 Venice 在精选模型上支持 prompt 缓存，以减少重复内容的延迟和成本。对于支持的模型，Venice 会自动缓存系统 prompt——无需更改代码。您也可以使用消息内容上的 `cache_control` 属性手动标记要缓存的内容。 | 参数 | 类型 | 说明 | | ------------------ | ------ | ------------------------------------------------------------- | | `prompt_cache_key` | string | 用于提升缓存命中率的可选路由提示。提供时，Venice 会将请求路由到相同的后端基础设施，提高多轮对话中缓存命中的可能性。 | 有关缓存如何工作、计费和最佳实践的详细信息，请参阅 [Prompt 缓存](/guides/features/prompt-caching)。 ## 响应头参考 所有 Venice API 响应都包含提供请求元数据、速率限制、模型信息和账户余额的 HTTP 头。除了 API 响应返回的错误代码外，您还可以检查这些头部以获取特定 API 请求的唯一 ID、监控速率限制并跟踪您的账户余额。 Venice 建议在生产部署中记录请求 ID（`CF-RAY` 头），以便在需要时与我们的支持团队进行更高效的故障排查。 下表提供了您可能遇到的所有头部的全面参考： | Header | 类型 | 用途 | 何时返回 | | ------------------------------------------- | ------ | --------------------------------------------------------- | --------------------------- | | **标准 HTTP 头部** | | | | | `Content-Type` | string | 响应体的 MIME 类型（`application/json`、`text/csv`、`image/png` 等） | 始终 | | `Content-Encoding` | string | 用于压缩响应体的编码（`gzip`、`br`） | 当客户端发送 `Accept-Encoding` 头时 | | `Content-Disposition` | string | 内容应如何显示（例如 `attachment; filename=export.csv`） | 下载文件或导出时 | | `Date` | string | 响应生成时的 RFC 7231 格式时间戳 | 始终 | | **请求标识** | | | | | `CF-RAY` | string | 此 API 请求的唯一标识符，用于故障排查和支持请求 | 始终 | | `x-venice-version` | string | Venice API 服务的当前版本/修订（例如 `20250828.222653`） | 始终 | | `x-venice-timestamp` | string | 处理请求时的服务器时间戳（ISO 8601 格式） | 启用时间戳跟踪时 | | `x-venice-host-name` | string | 处理请求的服务器主机名 | 错误响应和调试场景 | | **模型信息** | | | | | `x-venice-model-id` | string | 请求所用 AI 模型的唯一标识符（例如 `venice-01-lite`） | 使用 AI 模型的推理端点 | | `x-venice-model-name` | string | 所用 AI 模型的友好/显示名称（例如 `Venice Lite`） | 使用 AI 模型的推理端点 | | `x-venice-model-router` | string | 处理模型推理的路由器/后端服务 | 当路由信息可用时的推理端点 | | `x-venice-model-deprecation-warning` | string | 计划弃用模型的警告消息 | 使用已弃用模型时 | | `x-venice-model-deprecation-date` | string | 模型将被弃用的日期（ISO 8601 日期） | 使用已弃用模型时 | | **速率限制信息** | | | | | `x-ratelimit-limit-requests` | number | 当前时间窗口内允许的最大请求数 | 所有已认证请求 | | `x-ratelimit-remaining-requests` | number | 当前时间窗口内剩余的请求数 | 所有已认证请求 | | `x-ratelimit-reset-requests` | number | 请求速率限制重置时的 Unix 时间戳 | 所有已认证请求 | | `x-ratelimit-limit-tokens` | number | 时间窗口内允许的最大 token 数（prompt + completion） | 所有已认证请求 | | `x-ratelimit-remaining-tokens` | number | 当前时间窗口内剩余的 token 数 | 所有已认证请求 | | `x-ratelimit-reset-tokens` | number | 距离 token 速率限制重置的秒数 | 所有已认证请求 | | `x-ratelimit-type` | string | 应用的速率限制类型（`user`、`api_key`、`global`） | 当强制执行速率限制时 | | **分页头部** | | | | | `x-pagination-limit` | number | 每页项目数 | 分页端点 | | `x-pagination-page` | number | 当前页码（从 1 开始） | 分页端点 | | `x-pagination-total` | number | 所有页面的项目总数 | 分页端点 | | `x-pagination-total-pages` | number | 总页数 | 分页端点 | | **账户余额信息** | | | | | `x-venice-balance-diem` | string | 处理请求前您的 DIEM token 余额 | 所有已认证请求 | | `x-venice-balance-usd` | string | 处理请求前您的美元信用余额 | 所有已认证请求 | | **内容安全头部** | | | | | `x-venice-is-blurred` | string | 指示生成的图像是否因内容政策被模糊处理（`true`/`false`） | 启用 Safe Venice 的图像生成 | | `x-venice-is-content-violation` | string | 指示内容是否违反 Venice 的内容政策（`true`/`false`） | 内容生成端点 | | `x-venice-is-adult-model-content-violation` | string | 指示内容是否违反成人模型内容政策（`true`/`false`） | 图像生成端点 | | `x-venice-contains-minor` | string | 指示图像是否包含未成年人（`true`/`false`） | 启用年龄检测的图像分析端点 | | **客户端信息** | | | | | `x-venice-middleface-version` | string | Venice middleface 客户端的版本 | 来自 Venice middleface 客户端的请求 | | `x-venice-mobile-version` | string | Venice 移动应用客户端的版本 | 来自移动应用的请求 | | `x-venice-request-timestamp-ms` | number | 客户端提供的请求时间戳（毫秒） | 当客户端在请求中提供时间戳时 | | `x-venice-control-instance` | string | 用于调试的控制实例标识符 | 用于调试的图像生成端点 | | **身份验证头部** | | | | | `x-auth-refreshed` | string | 指示身份验证 token 在请求期间已刷新（`true`/`false`） | 当身份验证 token 自动刷新时 | | `x-retry-count` | number | 请求的重试次数 | 当发生请求重试时 | ### 重要说明 * **头部名称大小写**：HTTP 头部不区分大小写，但 Venice 为保持一致性使用小写加连字符 * **字符串值**：头部中的布尔值以字符串形式返回（`"true"` 或 `"false"`） * **数值**：大数字和余额值可能以字符串形式返回，以避免精度丢失 * **可选头部**：并非所有头部都会在每个响应中返回；是否存在取决于端点和请求上下文 * **压缩**：在请求中使用 `Accept-Encoding: gzip, br` 以在支持的地方接收压缩响应 ### 示例：访问响应头部 ```javascript theme={"system"} // After making an API request, access headers from the response object const requestId = response.headers.get('CF-RAY'); const remainingRequests = response.headers.get('x-ratelimit-remaining-requests'); const remainingTokens = response.headers.get('x-ratelimit-remaining-tokens'); const usdBalance = response.headers.get('x-venice-balance-usd'); // Check for model deprecation warnings const deprecationWarning = response.headers.get('x-venice-model-deprecation-warning'); if (deprecationWarning) { console.warn(`Model Deprecation: ${deprecationWarning}`); } ``` ## 最佳实践 1. **速率限制**：监控 `x-ratelimit-remaining-requests` 和 `x-ratelimit-remaining-tokens` 头部并实现指数退避 2. **余额监控**：跟踪 `x-venice-balance-usd` 和 `x-venice-balance-diem` 头部以避免服务中断 3. **系统 prompt**：在启用和不启用 Venice 系统 prompt 的情况下进行测试，以找到最适合您用例的方式 4. **API 密钥**：妥善保管 API 密钥并定期轮换 5. **请求日志**：记录 `CF-RAY` 头部值以便与支持团队进行故障排查 6. **模型弃用**：使用模型时检查 `x-venice-model-deprecation-warning` 头部 ## 与 OpenAI API 的差异 虽然 Venice 与 OpenAI API 规范保持高度兼容，但仍存在一些关键差异： 1. **venice\_parameters**：额外的配置项如 `enable_web_search`、`character_slug` 和 `strip_thinking_response`，用于扩展功能 2. **系统 prompt**：Venice 将您的系统 prompt 附加到针对无审查响应优化的默认值之后（使用 `include_venice_system_prompt: false` 禁用） 3. **模型生态**：Venice 提供自己的[模型阵容](/overview/models)，包括无审查模型和推理模型——使用 Venice 模型 ID 而非 OpenAI 映射 4. **响应头**：用于余额跟踪的独特头部（`x-venice-balance-usd`、`x-venice-balance-diem`）、模型弃用警告和内容安全标志 5. **内容政策**：更宽松的政策，配有专门的无审查模型和可选的内容过滤 ## API 稳定性 Venice 对 v1 端点和参数保持向后兼容。有关模型生命周期政策、弃用通知和迁移指南，请参阅[弃用](/overview/deprecations)。 ## OpenAPI 规范与原始数据 为以编程方式访问 Venice API 文档和数据（包括与 RAG 检索增强生成一起使用），以下资源可用： * [OpenAPI 规范（YAML）](https://api.venice.ai/doc/api/swagger.yaml) — 完整的 API 规范，YAML 格式 * [API 文档源码](https://github.com/veniceai/api-docs/archive/refs/heads/main.zip) — 所有文档页面（`.mdx` 格式）的可下载归档 *** 本文档中未列出的请求字段可能会被透传，但不保证经过验证或正常工作。