API Reference | Venice API Docs

Venice API 提供基于 HTTP 的 REST 和流式接口，用于构建使用无审查模型与私有推理的 AI 应用。您可以创建文本生成、图像生成、嵌入向量等内容，所有这些都不受限制性内容政策的约束。集成示例和 SDK 可在文档中查看。我们的 API 参考也可作为 OpenAPI YAML 规范使用。

身份验证

Venice API 使用 API 密钥进行身份验证。在您的 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）并发起首个请求：

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!"}]
  }'

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);

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 的方式：

默认行为：您的系统 prompt 会附加到 Venice 的默认值之后
自定义行为：完全禁用 Venice 的系统 prompt

禁用 Venice 系统 prompt

使用 venice_parameters 选项移除 Venice 的默认系统 prompt：

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
    }
  }'

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,
  },
});

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	从响应中剥离 `<think></think>` 块（适用于使用旧版 `<think>` 标签格式的模型）。请参阅推理模型。	`false`
`disable_thinking`	boolean	在支持的推理模型上，禁用思考过程并从响应中剥离 `<think></think>` 块	`false`
`enable_web_search`	string	为此请求启用网页搜索（`off`、`on`、`auto` - auto 由模型自行决定是否启用）会产生额外的按用量计费，请参阅定价。	`off`
`enable_web_scraping`	boolean	启用对用户消息中检测到的最多 5 个 URL 的网页抓取。抓取的内容会增强响应并绕过网页搜索。仅对成功抓取的 URL 计费。会产生额外的按用量计费，请参阅定价。	`false`
`enable_x_search`	boolean	为支持的 Grok 模型（如 `grok-4-20-beta`）启用 xAI 原生搜索（web + X/Twitter）。通过使用 xAI 的搜索基础设施提供更高质量的搜索结果。启用后，Venice 标准的网页搜索会被绕过。会产生额外的按用量计费，请参阅定价。	`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）。详细信息请参阅模型功能后缀。

Prompt 缓存

Venice 在精选模型上支持 prompt 缓存，以减少重复内容的延迟和成本。对于支持的模型，Venice 会自动缓存系统 prompt——无需更改代码。您也可以使用消息内容上的 cache_control 属性手动标记要缓存的内容。

参数	类型	说明
`prompt_cache_key`	string	用于提升缓存命中率的可选路由提示。提供时，Venice 会将请求路由到相同的后端基础设施，提高多轮对话中缓存命中的可能性。

有关缓存如何工作、计费和最佳实践的详细信息，请参阅 Prompt 缓存。

响应头参考

所有 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 以在支持的地方接收压缩响应

示例：访问响应头部

// 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}`);
}

最佳实践

速率限制：监控 x-ratelimit-remaining-requests 和 x-ratelimit-remaining-tokens 头部并实现指数退避
余额监控：跟踪 x-venice-balance-usd 和 x-venice-balance-diem 头部以避免服务中断
系统 prompt：在启用和不启用 Venice 系统 prompt 的情况下进行测试，以找到最适合您用例的方式
API 密钥：妥善保管 API 密钥并定期轮换
请求日志：记录 CF-RAY 头部值以便与支持团队进行故障排查
模型弃用：使用模型时检查 x-venice-model-deprecation-warning 头部

与 OpenAI API 的差异

虽然 Venice 与 OpenAI API 规范保持高度兼容，但仍存在一些关键差异：

venice_parameters：额外的配置项如 enable_web_search、character_slug 和 strip_thinking_response，用于扩展功能
系统 prompt：Venice 将您的系统 prompt 附加到针对无审查响应优化的默认值之后（使用 include_venice_system_prompt: false 禁用）
模型生态：Venice 提供自己的模型阵容，包括无审查模型和推理模型——使用 Venice 模型 ID 而非 OpenAI 映射
响应头：用于余额跟踪的独特头部（x-venice-balance-usd、x-venice-balance-diem）、模型弃用警告和内容安全标志
内容政策：更宽松的政策，配有专门的无审查模型和可选的内容过滤

API 稳定性

Venice 对 v1 端点和参数保持向后兼容。有关模型生命周期政策、弃用通知和迁移指南，请参阅弃用。

OpenAPI 规范与原始数据

为以编程方式访问 Venice API 文档和数据（包括与 RAG 检索增强生成一起使用），以下资源可用：

OpenAPI 规范（YAML） — 完整的 API 规范，YAML 格式
API 文档源码 — 所有文档页面（.mdx 格式）的可下载归档

_{本文档中未列出的请求字段可能会被透传，但不保证经过验证或正常工作。}

Venice APIs

简介

身份验证

OpenAI 兼容性

设置

Venice 专有功能

系统 prompt

禁用 Venice 系统 prompt

Venice 参数

Prompt 缓存

响应头参考

重要说明

示例：访问响应头部

最佳实践

与 OpenAI API 的差异

API 稳定性

OpenAPI 规范与原始数据

​身份验证

​OpenAI 兼容性

​设置

​Venice 专有功能

​系统 prompt

​禁用 Venice 系统 prompt

​Venice 参数

​Prompt 缓存

​响应头参考

​重要说明

​示例：访问响应头部

​最佳实践

​与 OpenAI API 的差异

​API 稳定性

​OpenAPI 规范与原始数据

身份验证

OpenAI 兼容性

设置

Venice 专有功能

系统 prompt

禁用 Venice 系统 prompt

Venice 参数

Prompt 缓存

响应头参考

重要说明

示例：访问响应头部

最佳实践

与 OpenAI API 的差异

API 稳定性

OpenAPI 规范与原始数据