Venice Chat Completions

POST /api/v1/chat/completions is Venice's main text endpoint. It's OpenAI-compatible, plus a venice_parameters object for Venice-only features.

Use when

• You need LLM text generation, with or without tools, with or without streaming.
• You want multimodal inputs (images, audio, video) to a vision/audio-capable model.
• You want Venice-specific features: web search, E2EE, characters, xAI X/Twitter search, strip-thinking, web scraping.
• You need prompt caching for large system prompts or long documents.
• You need structured (json_schema) output.

For the newer Alpha Responses API, see [venice-responses](../venice-responses/SKILL.md).

Minimal request

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

Response shape is the standard OpenAI chat.completion object (id, object: "chat.completion", choices[].message, usage). With stream: true, responses come as SSE data: lines in chat.completion.chunk format.

The request body

Core fields (OpenAI-compatible)

venice_parameters (Venice-only)

All optional. Combined with model feature suffixes, these are how you enable Venice features.

Model feature suffixes

Some veniceparameters can also be expressed as model feature suffixes on the model string — useful when the caller/library (OpenAI SDK, LangChain) can't set veniceparameters. Syntax:

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

Values are URL-decoded. Supported keys (exact match):

Unknown keys are silently ignored. Examples:

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

Note: enablee2ee and enablexsearch can only be set via veniceparameters, not as suffixes.

Messages and modalities

messages[].content is either a string or an array of typed parts. Roles: user, assistant, tool, system, developer (reasoning models like o-series / codex).

Text + image (image_url)

{
  "model": "zai-org-glm-5-1",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ]
  }]
}

• url accepts a public URL or data:image/png;base64,....
• Models with modelspec.capabilities.supportsMultipleImages: true preserve images across the whole conversation; single-image vision models only keep images from the last user message. Check modelspec.capabilities.maxImages for the per-request cap.

Audio input (input_audio)

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Transcribe this clip."},
    {"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}}
  ]
}

Formats: wav, mp3, aiff, aac, ogg, flac, m4a, pcm16, pcm24. Audio URLs are not supported — always inline base64.

Video input (video_url)

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Summarize this."},
    {"type": "video_url", "video_url": {"url": "https://www.youtube.com/watch?v=..."}}
  ]
}

Accepts public URLs (including YouTube for some providers) or data:video/mp4;base64,.... Supported formats: mp4, mpeg, mov, webm.

Prompt caching (cache_control)

Any text / imageurl / inputaudio / video_url part can carry:

{"cache_control": {"type": "ephemeral", "ttl": "1h"}}

Combine with promptcachekey and promptcacheretention: "24h" on the root request for predictable cache routing. Cache read / write pricing is model-specific — check model_spec.pricing on /models.

Tools & function calling

Function tools

{
  "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"
}

• toolchoice can also be "required", "none", or {"type":"function","function":{"name":"getweather"}}.
• paralleltoolcalls: true (default) lets the model emit multiple calls at once.
• Respond by appending {"role":"tool","toolcallid":"...","content":"..."} before the next call.

Built-in tools

"tools": [{"type": "web_search"}, {"type": "x_search"}]

Equivalent to toggling veniceparameters.enablewebsearch / enablexsearch. xsearch requires a model with supportsXSearch.

Reasoning models

On thinking models (GLM 5.1, Kimi K2.6, Claude Opus 4.7, GPT-5.4 Pro, …):

{
  "model": "zai-org-glm-5-1",
  "reasoning": {"effort": "medium", "summary": "auto"},
  "venice_parameters": {"strip_thinking_response": false},
  "messages": [...]
}

• reasoning_effort is the OpenAI-compatible flat variant (takes precedence over reasoning.effort).
• Reasoning models may return reasoningcontent or structured reasoningdetails[] on the assistant message. Pass reasoning_details back verbatim in the next turn — it encodes thought signatures for providers like Claude Opus 4.7 and GPT-5.4 Pro.
• Use veniceparameters.disablethinking: true to skip thinking entirely on supported models.

Structured output (response_format)

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "type": "object",
      "properties": {"name": {"type": "string"}, "age": {"type": "number"}},
      "required": ["name", "age"]
    }
  }
}

Prefer jsonschema over the legacy jsonobject. Plain text is the default ({"type": "text"}).

E2EE (end-to-end encryption)

For models advertising supportsE2EE:

1. Perform an HPKE / Noise handshake with Venice (see docs.venice.ai/e2ee).
2. Send encrypted payload with the required E2EE request headers.
3. Leave veniceparameters.enablee2ee at default true, or set false to fall back to TEE-only.

E2EE is not supported on /responses — use /chat/completions for encrypted inference.

Streaming

{"stream": true, "stream_options": {"include_usage": true}}

• Response is text/event-stream. Each event is data: {...chunk...}\n\n, terminated by data: [DONE].
• include_usage: true adds a final chunk with token counts.
• With veniceparameters.includesearchresultsinstream: true, the first chunk carries venicesearch_results.

Web-search answers

When enablewebsearch is "auto" or "on", the response includes veniceparameters.websearchcitations[] where each entry has url, title, content (snippet), and date. Turn on enableweb_citations to have the model insert ^1^ superscripts inline.

Error handling specifics

• 402 — insufficient balance. Bearer: INSUFFICIENTBALANCE. x402: PAYMENTREQUIRED with structured topUpInstructions and siwxChallenge.
• 422 — prompt violates Venice or provider content policy. May include suggested_prompt.
• 413 — payload too large (mostly vision/audio).
• 429 — rate limit. See /apikeys/ratelimits and [venice-errors](../venice-errors/SKILL.md).

Common gotchas

• maxtokens is deprecated — prefer maxcompletion_tokens.
• Image URLs must be publicly reachable from Venice's network. Localhost / signed S3 URLs without public access fail.
• Audio inputs cannot be URLs — always base64.
• Single-image vision models drop older images on each turn; chain them into the last user message.
• For multi-turn with tools on Claude Opus 4.7, GPT-5.4 Pro, and similar, always round-trip reasoning_details unchanged.
• paralleltoolcalls: true means you MUST be prepared to execute several tools in parallel before sending a single tool-role reply chain.
• characterslug replaces the default Venice system prompt. Combine with includevenicesystemprompt: false for total control.