venice-models

Venice Models

用于发现模型的三个只读端点——全部为 GET，且均公开：

端点	返回内容
/models	模型目录，包含 model_spec（能力、限制和定价）。
/models/traits	特征 → 模型 ID 映射（例如 default、default_reasoning、highest_quality）。
/models/compatibility_mapping	旧版 / 第三方模型 ID → Venice 模型 ID 别名。

身份验证为可选项。 这些路由无需 API 密钥，因此直接使用普通的 curl 即可。如果发送 Authorization: Bearer $VENICE_API_KEY，结果会针对该调用方进行定制：密钥的 modelPrivacy 设置会筛选列表，启用了 beta 标记的账户还会看到 beta 模型，合作伙伴账户则会看到协商后的费率。无效密钥不会被拒绝——你只会看到公开视图。

?type= 的取值（省略时默认为 text）：

取值	/models	/models/traits	/models/compatibility_mapping
text、image、video、music、tts、asr、embedding、upscale、inpaint、decision	是	是	是
all（所有类型）	是	是	400
code（capabilities.optimizedForCode: true 的文本模型）	是	是	400

任何其他值都会返回 400 { "error": "Invalid request parameters", "details": …, "issues": … }。

music 包含长篇音频（歌曲、音效、ElevenLabs 旁白模型）以及所有变声模型。decision 列出 POST /decisions 使用的类型化判断模型（目前为 jev-latest，标记为 betaModel: true）——参见 venice-decisions。

适用场景

• 你需要根据能力（视觉、推理、函数调用、E2EE、X 搜索、多图输入等）在运行时选择模型。
• 你需要根据模型的 constraints（提示词长度、宽高比、分辨率、步数、时长）验证请求。
• 你需要获取当前每百万 token / 每张图像 / 每秒 / 每百万字符的价格，以估算成本。
• 你想将某个特征（default、default_reasoning、highest_quality）或旧版别名（gpt-4o）解析为具体的 Venice 模型 ID。

GET /models

curl "https://api.venice.ai/api/v1/models?type=text"

{
  "object": "list",
  "type": "text",
  "data": [
    {
      "id": "zai-org-glm-5-2",
      "object": "model",
      "owned_by": "venice.ai",
      "type": "text",
      "created": 1781568000,
      "context_length": 1000000,
      "model_spec": {
        "name": "GLM 5.2",
        "description": "GLM-5.2 is the next-generation large language model…",
        "availableContextTokens": 1000000,
        "maxCompletionTokens": 131072,
        "privacy": "private",
        "modelSource": "https://huggingface.co/zai-org/GLM-5.2",
        "offline": false,
        "traits": ["default", "function_calling_default"],
        "capabilities": { "supportsReasoning": true, "reasoningEffortOptions": ["none", "high", "max"], "…": "…" },
        "pricing": {
          "input":       { "usd": 1.4,  "diem": 1.4 },
          "cache_input": { "usd": 0.26, "diem": 0.26 },
          "output":      { "usd": 4.4,  "diem": 4.4 }
        }
      }
    }
  ]
}

顶层 ModelResponse 字段

字段	说明
id	作为 model 发送的模型 ID。
object / owned_by	始终为 "model" / "venice.ai"。
type	上述 10 种模型类型之一。
created	Unix 秒数——模型在 Venice API 上的发布日期。
context_length	仅适用于文本模型。与 OpenAI 兼容的 model_spec.availableContextTokens 镜像字段。
discount_to_user	仅适用于转售商（0 < x < 1）。仅返回给所属协议中的转售合作伙伴，其他调用方不会看到此字段——缺失时应视为没有折扣。
model_spec	以下所有内容。

model_spec - 通用字段

字段	用途
name、description、modelSource	显示名称、简介、上游 URL（description / modelSource 可能不存在）。
privacy	private（零数据留存）或 anonymized（第三方提供商；不会与你的身份关联）。
offline	true ⇒ 请求返回 503 "The model is temporarily offline"。请跳过。
traits	此模型当前具有的特征名称（可能为 []）。
uncensored	仅当 Venice 将模型（所有模态）归类为不受审查时才会存在且为 true。否则不存在，不会是 false。上游提供商仍可能进行过滤。
betaModel	模型处于 Beta 状态（仍可调用）。
beta	模型仅限拥有 Beta 访问权限的账户使用。仅出现在返回给此类账户的列表中。
regionRestrictions	模型被屏蔽的国家/地区代码（OpenAPI 描述写的是“预期可用”，但来自列出国家/地区的请求会遭到拒绝）。这类请求会收到 403 "The specified model is unavailable in …". 不受限制的模型不会有此字段。
deprecation	{ autoRemap, date, removesAt, replacementModelId?, startsAt? } - 仅当已安排退役时存在。模型会在 removesAt 时从 /models 中移除；autoRemap: true 表示 Venice 可能会将针对该 ID 的请求重定向到 replacementModelId，而不是返回错误。
model_sets	仅适用于文本、图像和视频。策展标签，例如 venice_recommendations、featured，以及视频的 audio、uncensored、high_resolution、fast 等（实时提供，但未在 OpenAPI 架构中声明）。

model_spec.capabilities - 文本模型

标志	含义
optimizedForCode	针对编码任务调优（用于 ?type=code）。
quantization	fp4 / fp8 / fp16 / bf16 / int8 / int4 / not-available。
supportsFunctionCalling	允许使用 tools。
supportsResponseSchema	支持 response_format: { type: "json_schema" }。
supportsReasoning	模型会输出推理内容。
supportsReasoningEffort	支持 reasoning_effort / reasoning.effort。为 true 时，还会提供 reasoningEffortOptions（none、minimal、low、medium、high、xhigh、max 的子集；none 表示可以关闭推理）和 defaultReasoningEffort。
supportsVision	接受 image_url 部分。
supportsMultipleImages + maxImages	每个请求允许传入多张图像；maxImages 是模型声明的上限。Chat 将每条消息中的图像数量硬性限制为最多 10 张。
supportsVideoInput + maxVideos	接受 video_url 部分；部分模型会提供 maxVideos。
supportsAudioInput	接受 input_audio 部分。
supportsWebSearch	venice_parameters.enable_web_search - 目前所有文本模型均为 true。
supportsXSearch	通过 venice_parameters.enable_x_search 使用 xAI 原生网页和 X 搜索。
supportsLogProbs	支持 logprobs / top_logprobs。
supportsTeeAttestation	在 TEE 中运行；可通过 GET /tee/attestation / /tee/signature 验证。
supportsE2EE	端到端加密推理（需要 TEE）。

model_spec.constraints 和特定类型字段

• 文本 - constraints 为可选项（只有少数模型包含此字段）：temperature.default、top_p.default，以及可选的 {frequency,presence,repetition}_penalty.default。
• 图像 - constraints：promptCharacterLimit、widthHeightDivisor、steps.{default,max}、可选的 aspectRatios[] + defaultAspectRatio、可选的 resolutions[] + defaultResolution、可选的 qualities[] + defaultQuality（接受 quality 的模型）、可选的 maxStyleReferences + supportsStyleReferenceStrength。此外还有：supportsStyleReferences，以及 supportsWebSearch 和 supportsOptimizePromptThinking（实时提供，不在 OpenAPI 架构中）。
• 局部重绘 / 编辑 - constraints：aspectRatios[]、promptCharacterLimit、combineImages、可选的 maxInputImages、singleImageAspectRatio（如果为 false，单图编辑会保留输入尺寸并忽略 aspect_ratio）、可选的 resolutions[]/defaultResolution、qualities[]/defaultQuality。此外还有：supportsOptimizePromptThinking。
• 视频 - constraints：model_type（text-to-video / image-to-video / video）、aspect_ratios[]、resolutions[]、durations[]（例如 "5s"；大多数升频和视频转视频模型会列出 "Auto"，表示源视频时长——对此类模型请省略 duration）、audio、audio_configurable、audio_input、per_reference_audio、video_input、可选的 prompt_character_limit（默认值为 2500）、可选的 reference_image_min_short_side_pixels、reference_image_min_aspect_ratio、reference_image_max_aspect_ratio，以及仅增强模型包含的 topaz 块（models、sliders、selects、no_upscale_models、h264_output、prompt）。audio_input … reference_image_* 键会实时提供，但未在 OpenAPI 架构中声明。
• TTS（model_spec 顶层）- voices[]、default_format、supported_formats[]（不在此列表中的显式格式会被拒绝）、supports_custom_voice_id，以及面向可供你使用克隆功能的模型提供的 voice_cloning { mode: "zero_shot" | "persistent", accepted_formats[], min_sample_seconds, retention_days }（请结合 POST /audio/voices 使用，参见 venice-audio-speech）。此处不会公开模型级别的 prompt / temperature / top_p 支持开关——请将 venice-audio-speech 中的逐模型表格作为支持矩阵（已发布的架构文本不完整）。
• 音乐 / 音频生成（顶层）- supports_lyrics、lyrics_required、supports_force_instrumental、supports_lyrics_optimizer（实时提供，不在 OpenAPI 架构中）、supports_loop、supports_custom_voice_id、supports_language_code、supports_speed、supported_formats[]、default_format、prompt_character_limit、min_prompt_length、可选的 lyrics_character_limit、duration_options[]、min_duration / max_duration / default_duration、voices[] / default_voice、default_speed / min_speed / max_speed。
• 变声器（voice_changer: true 的音乐模型）- 添加 supports_background_noise_removal、supports_seed、accepted_audio_formats[]、max_source_audio_duration_seconds。这些模型通过 /audio/voice-changer/* 运行，而非 /audio/queue——参见 venice-audio-voice-changer。目前没有公开列出的变声器模型；使用前请检查 ?type=music 中是否有 voice_changer: true。
• 嵌入（顶层）- embeddingDimensions、maxInputTokens、supportsCustomDimensions（仅在值为 true 时出现）。
• 决策（顶层）- maxStateTokens（状态 + 最长问题）、maxTotalTokens（状态 + 所有问题）。
• ASR / 升频 - 除通用字段和 pricing 外，没有额外字段。

model_spec.pricing - 按类型

每个价格都是 { usd, diem }；目前 diem 始终等于 usd。价格已包含当前适用于调用账户的任何促销折扣（某些促销设有等级限制，因此匿名调用者和 Pro 调用者看到的价格可能不同）——请使用你将用于付费的同一组凭据查询价格。

• 文本 / 嵌入 / 决策 - input 和 output 按每 1 000 000 个令牌计价，可选的 cache_input（缓存读取）、cache_write（创建缓存，例如 Anthropic），以及 extended { context_token_threshold, input, output, cache_input?, cache_write? }。当输入令牌数超过阈值时，扩展费率适用于整个请求。
• 图像 - generation（每张图像的固定价格）或 resolutions.<1K|2K|4K>；可选的 quality.<resolution>.<low|medium|high>；始终包含 upscale.{2x,4x} 块（这是通用的放大价格，并不表示此模型支持放大，也不享受促销折扣）。
• 放大（upscaler）- 形状与图像相同：generation + upscale.{2x,4x}。
• 局部重绘 / 编辑 - inpaint 按每次编辑计价，可选的 resolutions.*、可选的 inputImages { included, additional }（超出 included 的每张输入图像收取附加费），以及可选的 quality.*。
• 视频 - /models 中没有 pricing。请使用 POST /video/quote（参见 venice-video）。
• 音乐 - 仅包含以下一种：generation（每个任务）、durations.<ceiling_seconds> { usd, diem, min_seconds, max_seconds }、per_second 或 per_thousand_characters。请使用 POST /audio/quote 获取准确价格。
• TTS - input 按每 1 000 000 个输入字符计价。
• ASR - per_audio_second。

加密货币 RPC 定价不在 /models 中——参见 venice-crypto-rpc。

GET /models/traits

curl "https://api.venice.ai/api/v1/models/traits?type=text"

{
  "object": "list",
  "type": "text",
  "data": {
    "default": "zai-org-glm-5-2",
    "function_calling_default": "zai-org-glm-5-2",
    "default_reasoning": "kimi-k3",
    "default_code": "deepseek-v4-pro-0813",
    "default_vision": "qwen-3-8-27b",
    "most_intelligent": "grok-4-7",
    "most_uncensored": "venice-uncensored-1-2"
  }
}

可能的 trait 键：default、fastest、most_uncensored、eliza-default（任意类型）、default_code、default_reasoning、default_vision、function_calling_default、most_intelligent（文本）、highest_quality（图像）。仅当某个模型持有相应 trait 时，该键才会出现——目前文本类型尚未分配 fastest。目前只有 text 和 image（以及由它们构成的 all / code 筛选器）会返回非空映射。?type=all 会将所有类型合并到一个映射中，因此不同类型之间相同的键会发生冲突——例如，default 在该映射中会解析为图像模型。以上值是一个快照；请在运行时解析。

trait 名称也可以直接作为 model 传入（例如 "model": "default_reasoning"），Venice 会针对每个请求进行解析。

GET /models/compatibility_mapping

curl "https://api.venice.ai/api/v1/models/compatibility_mapping?type=text"

{
  "object": "list",
  "type": "text",
  "data": {
    "gpt-4o": "llama-3.3-70b",
    "gpt-4.1": "qwen3-235b-a22b-instruct-2507",
    "claude-3-5-sonnet-20241022": "llama-3.3-70b",
    "qwen3-235b": "qwen3-235b-a22b-thinking-2507"
  }
}

键是旧版 OpenAI / Anthropic / Venice ID；值是每个 ID 对应解析到的 Venice 模型。?type=embedding 目前会将 text-embedding-ada-002 映射到 text-embedding-bge-m3；其他类型为空。与 trait 一样，别名也可以直接作为 model 传入。将硬编码旧版 OpenAI ID 的代码移植过来时，这很有用——但请检查目标模型的能力，因为映射仅基于 ID。

常见模式

在运行时选择视觉 + 推理模型

const base = 'https://api.venice.ai/api/v1'
const list = await fetch(`${base}/models?type=text`).then(r => r.json())
const match = list.data.find((m: any) =>
  m.model_spec.capabilities.supportsVision &&
  m.model_spec.capabilities.supportsReasoning &&
  !m.model_spec.offline &&
  !m.model_spec.deprecation
)

提交前验证图像请求

const spec = (await fetch(`${base}/models?type=image`).then(r => r.json()))
  .data.find((m: any) => m.id === myModel)!.model_spec

const { widthHeightDivisor, promptCharacterLimit, aspectRatios } = spec.constraints
if (prompt.length > promptCharacterLimit) throw new Error('prompt too long')
if (width % widthHeightDivisor !== 0) throw new Error('width not divisible')
if (aspectRatios && !aspectRatios.includes(myAspect)) throw new Error('bad aspect')

估算大模型成本

// textSpec = model_spec of a text model from /models?type=text
// inputTokens = total prompt tokens, including cachedTokens
const p = textSpec.pricing
const tier = p.extended && inputTokens > p.extended.context_token_threshold ? p.extended : p
const cacheRate = tier.cache_input?.usd ?? tier.input.usd
const cost =
  ((inputTokens - cachedTokens) / 1_000_000) * tier.input.usd +
  (cachedTokens / 1_000_000) * cacheRate +
  (outputTokens / 1_000_000) * tier.output.usd

带有 cache_write 的模型，其缓存写入令牌按该费率计费，而非按 input 费率计费。

注意事项

• 目录会变化——缓存几分钟即可，不要缓存几天。本技能中的模型 ID 是快照；请务必通过 /models 确认。
• 省略 ?type 只会返回文本。要获取所有内容，请使用 ?type=all。
• 视频的 model_spec.pricing 始终缺失；任何未公布价格的模型也可能缺少此字段——请防范 undefined。
• regionRestrictions 列出的是受限国家，而非允许的国家。
• uncensored 缺省时表示未提供，而非 false——请使用 === true 进行判断。
• 特征和别名因 type 而异——没有全局默认值；请务必传入 ?type=...。
• 仅限私有模型的 API 密钥（modelPrivacy: PRIVATE_TEXT / PRIVATE_ONLY）只能看到筛选后的列表；未经身份验证的调用则能看到所有公开内容。
• 有些字段会实时提供，但未包含在 OpenAPI ModelResponse 架构中（model_sets、图像的 supportsWebSearch、图像和修复的 supportsOptimizePromptThinking、音乐的 supports_lyrics_optimizer、若干视频约束键）。严格的生成式客户端可能会丢弃这些字段。