venice-api-overview

Venice API 概览

Venice AI 是一个兼容 OpenAI 的推理平台，支持文本、图像、音频、视频、嵌入和类型化决策。一个 API，两种付款方式：传统的 API 密钥（Venice 账户），或钱包（x402、Base 或 Solana 上的 USDC，无需账户）。

适用场景

• 你首次针对 api.venice.ai 编写代码。
• 你需要在 API 密钥和 x402／钱包身份验证之间作出选择。
• 你想快速了解不同任务对应的端点。
• 你需要了解常见的响应标头（x-ratelimit-*、PAYMENT-REQUIRED、弃用标头等）。

基础 URL

所有端点都位于以下路径下：

https://api.venice.ai/api/v1

OpenAPI 规范可通过 https://api.venice.ai/api/v1/swagger.yaml 获取（info.version 是 YYYYMMDD.HHMMSS 格式的时间戳；请从实时规范中读取）。

身份验证

方案	标头	最适用场景
BearerAuth	Authorization: Bearer $VENICE_API_KEY	服务端应用、账户管理、使用情况分析、DIEM／捆绑额度
siwx (x402)	SIGN-IN-WITH-X: <base64 SIWX JSON>（也接受旧版 X-Sign-In-With-X）	无需账户；使用 Base 或 Solana 上的 USDC 按量付费；无服务器环境／Agent

并非所有端点都同时接受两种方式：

端点	接受方式
所有推理端点：聊天、responses、嵌入、决策、图像、音频（语音、转录、音色、排队／检索／完成、变声排队／检索／完成）、视频排队／检索／完成、augment、POST /crypto/rpc/{network}	Bearer 或 SIWX
/api_keys/*（generate_web3_key 除外）、/billing/*（已退役的 /billing/usage 除外）、/characters/*	仅 Bearer（仅提供 SIGN-IN-WITH-X 标头会返回 401 Authentication failed）
/x402/balance/{wallet}、/x402/transactions/{wallet}	仅 SIWX（签名者必须拥有该钱包）
/models*、/image/styles、/video/quote（topaz-video-upscale 等升频模型除外：必须使用 Bearer 密钥，因此钱包无法为其获取报价）、/audio/quote、/audio/voice-changer/quote、/crypto/rpc/networks、/tee/attestation、/tee/signature、/api_keys/generate_web3_key、POST /x402/top-up	无需身份验证

任何需要凭据的路由（包括仅支持 Bearer 的路由）在请求中既没有 Authorization，也没有 SIGN-IN-WITH-X 标头时，都会返回包含 x402 发现信息的 402 响应（付款选项 + SIWX 挑战 + authOptions），而不是 401。请参阅 venice-auth。

# Bearer
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-2","messages":[{"role":"user","content":"hi"}]}'

// x402 wallet via the SDK (EVM / Base wallets)
import { VeniceClient } from 'venice-x402-client'
const v = new VeniceClient(process.env.WALLET_KEY!)
await v.models()

端点一览

推理

类别	端点	技能
聊天	POST /chat/completions	venice-chat
Responses（Alpha）	POST /responses	venice-responses
嵌入	POST /embeddings	venice-embeddings
决策（Beta）	POST /decisions（别名 POST /systemone）	venice-decisions
图像生成	POST /image/generate、POST /images/generations、GET /image/styles	venice-image-generate
图像编辑	POST /image/edit、POST /image/multi-edit、POST /image/upscale、POST /image/background-remove	venice-image-edit
TTS	POST /audio/speech、POST /audio/voices（语音克隆）	venice-audio-speech
STT	POST /audio/transcriptions	venice-audio-transcription
音乐 / 音频（异步）	POST /audio/quote、/audio/queue、/audio/retrieve、/audio/complete	venice-audio-music
变声器（异步）	POST /audio/voice-changer/quote、/queue、/retrieve、/complete	venice-audio-voice-changer
视频（异步）	POST /video/quote、/video/queue、/video/retrieve、/video/complete	venice-video

变声器：规范中包含这些端点，但目前没有公开列出的变声器模型——请先检查 GET /models?type=music，确认是否有 voice_changer: true 的模型。

目录

类别	端点	技能
模型	GET /models、/models/traits、/models/compatibility_mapping	venice-models
角色	GET /characters、/characters/{slug}、/characters/{slug}/reviews	venice-characters

GET /models?type= 接受 text（默认）、image、video、music、tts、asr、embedding、upscale、inpaint、decision，以及筛选项 all 和 code。

账户、账单、钱包

类别	端点	技能
API 密钥	GET/POST/PATCH/DELETE /api_keys、GET /api_keys/{id}、/api_keys/rate_limits、/api_keys/rate_limits/log、/api_keys/generate_web3_key	venice-api-keys
账单（Beta）	GET /billing/balance、/billing/usage-history、/billing/usage-analytics	venice-billing
x402 钱包	POST /x402/top-up、GET /x402/balance/{wallet}、GET /x402/transactions/{wallet}	venice-x402

实用工具

类别	端点	技能
加密 RPC 代理	GET /crypto/rpc/networks、POST /crypto/rpc/{network}	venice-crypto-rpc
增强	POST /augment/text-parser、/augment/scrape、/augment/search	venice-augment
TEE 验证	GET /tee/attestation、GET /tee/signature（公开，每个 IP 每分钟 10 次请求）	venice-text-routing

已退役（返回 410 Gone）

端点	替代方案
GET /billing/usage - 于 2026-09-16 停用	GET /billing/usage-history（游标分页：pageSize + nextCursor、startTimestamp / endTimestamp）
POST /video/transcriptions	对于 capabilities.supportsVideoInput 为 true 的模型，使用带有 video_url 部分的 POST /chat/completions

两者均会返回 410，并附带 Deprecation 和 Link: <…>; rel="successor-version" 标头（/billing/usage 还会发送 Sunset）。它们无需身份验证；每个 IP 每分钟 60 次请求的限制会对持续轮询的客户端返回 429。

需要留意的响应标头

标头	适用场景	含义
x-ratelimit-limit-requests / -remaining-requests / -reset-requests	大多数推理响应	账户的请求窗口——按模型计算（每分钟和每日限制中较严格的一个），或按视频／音频生成路由以及 /augment/scrape / /augment/search 端点计算。重置时间是以毫秒为单位的 Unix 时间戳。
x-ratelimit-limit-tokens / -remaining-tokens / -reset-tokens	受令牌数限制的文本模型	每分钟令牌数窗口（以毫秒为单位重置）。
x-ratelimit-remaining / x-ratelimit-resets	大多数需要凭据的路由响应	错误预算（30 秒窗口内允许失败的请求数），而不是请求配额。该值在当前响应计入之前读取，因此失败响应显示 1 意味着剩余次数为零。以毫秒为单位重置。
x-venice-balance-usd / x-venice-balance-diem	推理响应	请求开始时可用的余额（x402 调用方会在此处看到其钱包余额）。余额为零时不返回此标头；USD 数值不包括捆绑和赚取的额度。
x-venice-version	推理响应	服务器修订版本——提交错误报告时很有用。
x-venice-deprecated、x-venice-model-deprecation-date、x-venice-model-deprecation-warning、x-venice-deprecated-replacement	请求即将停用的模型（聊天、图像、视频队列）	停用日期和建议的替代项。
PAYMENT-REQUIRED	每个 x402 402：无凭据、钱包余额低于最低要求、/x402/top-up 发现请求，以及未提供 SIWX 的 /x402/balance / /x402/transactions	x402 v2 付款要求对象的 Base64 JSON（accepts[]，以及 sign-in-with-x 挑战；/x402/top-up 除外）。
Retry-After	429“模型过载”	需要等待的秒数（默认 30 秒）。
Deprecation / Sunset / Link	已停用的端点	参见上表。
Content-Encoding	发送 Accept-Encoding（gzip、br、deflate）时	所有路由都可能返回压缩响应，前提是响应正文足够大，值得压缩。规范在聊天、嵌入、决策和图像生成部分对此有说明。

规范还记录了 x402 响应中的 X-Balance-Remaining 标头，但当前服务器代码不会设置该标头——请读取 x-venice-balance-usd，或改为调用 GET /x402/balance/{wallet}。

定价模式概览

• 定价按请求动态计算，以 USD 计量。规范中收费的端点都包含 x-payment-info 区块（price.mode: dynamic、min: "0.001"、max: "10.00" USD）；POST /x402/top-up 的范围为 5-10000。只读路由（/models、报价接口）没有此区块。
• API 密钥账户的每个请求都从一种货币中扣费，优先顺序为 DIEM → 已赚取的额度 → 捆绑额度 → USD（参见 venice-billing）。每个密钥的 consumptionLimits 可以限制 USD / DIEM 支出。
• x402 钱包使用预付的 USDC 额度余额，可通过 Base 或 Solana 充值（最低充值 $5；请求开始时余额至少需要 $0.10）。与 Venice 账户关联且质押了 DIEM 的 EVM 钱包会优先使用 DIEM。
• 每个模型的价格可通过 GET /models → model_spec.pricing 获取，其中已包含账户当前可享受的促销优惠。视频价格不在此处提供——请使用 POST /video/quote；音乐／变声器可通过 /audio/quote 和 /audio/voice-changer/quote 获取准确报价。参见 venice-models。

标准错误格式

大多数错误如下：

{ "error": "Human-readable message" }

架构验证失败（400）会额外包含一个 details 树和一个 issues 数组：

{ "error": "Invalid request parameters", "details": { "_errors": [], "type": { "_errors": ["Invalid enum value…"] } }, "issues": [ … ] }

值得了解的例外：聊天中的上下文长度溢出会返回 OpenAI 风格的对象（{ "error": { "message", "type": "invalid_request_error", "param": "messages", "code": "context_length_exceeded" } }）；上游提供商拒绝请求时会返回提供商的消息（在跟踪 request_id 的路由上，例如聊天，还会包含 request_id）；x402 的 402 会返回结构化的充值数据。POST 请求的 Content-Type 既不是 application/json 也不是 multipart/form-data 时，会在运行身份验证之前返回 400 错误 "'Content-Type' must be 'application/json'"。完整表格和重试策略请参阅 venice-errors。

OpenAI 兼容性——支持与不支持的内容

• 可直接替换使用：/chat/completions、/responses、/embeddings、/images/generations、/audio/speech、/audio/transcriptions、/models。
• 为兼容性接受但会忽略的参数：user、store（用于聊天时）。user 不是 Venice 的 anon_user_id 的别名（但它确实会划分错误预算——参阅 venice-errors）。
• Venice 专属扩展位于 venice_parameters 下：/chat/completions 支持完整参数集，/responses 支持七个字段的子集（character_slug、enable_e2ee、enable_web_search、enable_web_scraping、enable_web_citations、include_venice_system_prompt、include_search_results_in_stream）。
• 模型特性后缀（例如 zai-org-glm-5-1:enable_web_search=on、kimi-k2-6:strip_thinking_response=true&disable_thinking=true）可通过模型 ID 切换 venice_parameters——参阅 venice-chat。
• 可以将特性名称（default_reasoning）或旧版别名（gpt-4o）作为 model 传入；Venice 会解析它。参阅 venice-models。

版本管理

• swagger.yaml 中的 info.version 是时间戳（YYYYMMDD.HHMMSS）。没有 /v2；功能会在单一 /api/v1 接口上持续更新，并通过以下方式控制：
  • 端点说明中的 Alpha/Beta 标签（Responses 为 Alpha；Decisions 和 Billing 为 Beta）。
  • /models 上的 betaModel / deprecation 元数据和能力标记。
• 已退役的端点会返回 410，并附带 Deprecation / Link 标头，而不会悄然消失。
• 依赖某项功能前，请务必检查模型的 model_spec.capabilities（supportsWebSearch、supportsReasoning、supportsE2EE、supportsXSearch、supportsMultipleImages、supportsFunctionCalling、supportsAudioInput、supportsVideoInput，等等）。

快速入门清单

1. 阅读 venice-auth，选择 Bearer 或 x402。
2. GET /models?type=…——选择一个模型，并记下其 model_spec.constraints 和 model_spec.pricing。
3. 按照相应的技能完成一次成功调用。
4. 使用 venice-errors 添加错误处理（402、422、429）。
5. 通过 x-ratelimit-* / x-venice-balance-* 标头、/billing/usage-history（仅限 ADMIN 密钥）或 /x402/transactions/{wallet}（钱包调用方）接入可观测性。