---

name: venice-responses description: Use Venice's Alpha POST /responses endpoint - an OpenAI-compatible, stateless Responses API with typed output blocks (reasoning, message, function_call, web_search_call). Covers request shape, input items, tools (function, web_search, x_search), reasoning controls, incomplete responses, streaming events, differences from /chat/completions, the supported venice_parameters subset, and E2EE behavior.

Venice Responses API (Alpha)

POST /api/v1/responses is Venice's OpenAI-compatible Responses endpoint. It returns a typed output array instead of a single message.content string — useful for agents that need to separate reasoning, messages, tool calls, and web-search events. Internally the request is translated to a chat completion, so model support matches venice-chat.

Alpha. The spec labels it Alpha (and its description still says "Alpha testers only"), but access is no longer restricted: any Bearer API key or x402 wallet can call it. Schemas may still change.

Use when

• A client library expects the OpenAI Responses shape (output[] with type: "reasoning" | "message" | "function_call" | "web_search_call").
• You want reasoning, message, and tool-call output cleanly separated.
• You want SSE streaming with typed events.

Otherwise use venice-chat — it has structured output, audio/video/file inputs, E2EE, sampling controls, and every venice_parameters field.

Limitations vs /chat/completions

Limitation	Detail
Stateless	Nothing is stored. Send the full history each call. previous_response_id, store, background are ignored.
No E2EE	E2EE-capable models return 400 unless venice_parameters.enable_e2ee: false (TEE-only mode). For encrypted inference use /chat/completions.
Text + image input only	input_text / input_image (and text / image_url parts). No audio, video, or file parts.
No structured output	text.format / response_format are dropped. Use /chat/completions.
Subset of venice_parameters	character_slug, enable_e2ee, enable_web_search, enable_web_scraping, enable_web_citations, include_venice_system_prompt, include_search_results_in_stream. Other keys (strip_thinking_response, disable_thinking, enable_x_search, return_search_results_as_documents) are silently dropped.
No model feature suffixes	model: "zai-org-glm-5-1:enable_web_search=on" resolves the model but ignores the suffix.
Few generation controls	Only temperature, top_p, max_output_tokens.

Authentication

Same as the rest of the API — Authorization: Bearer <key> or SIGN-IN-WITH-X: <SIWX> for x402 wallets. See venice-auth.

Minimal request

curl https://api.venice.ai/api/v1/responses \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5-1",
    "input": "Explain why the sky is blue in one paragraph."
  }'

OpenAI SDK (Python):

import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["VENICE_API_KEY"], base_url="https://api.venice.ai/api/v1")
resp = client.responses.create(model="zai-org-glm-5-1", input="Explain why the sky is blue.")
print(resp.output_text)

Request fields

Field	Notes
model	Required. Model ID, trait, or compatibility mapping.
input	Required. A string, or an array of input items (below).
max_output_tokens	Positive integer. Mapped to max_tokens; above the model's model_spec.maxCompletionTokens → 400 on models with an enforced cap.
temperature (0–2), top_p (0–1)	Sampling.
reasoning.effort	none | minimal | low | medium | high | xhigh | max (per-model support: model_spec.capabilities.reasoningEffortOptions). reasoning may be null.
reasoning.enabled	false disables reasoning on supported models and suppresses reasoning blocks. Ignored when an effort is set.
reasoning.summary	auto | concise | detailed. Accepted but not forwarded.
tools	See Tools.
tool_choice	"auto" | "none" | "required" | {"type":"function","function":{"name":"..."}}. Dropped when no function tools remain.
web_search	Boolean. true forces web search on (same as a {"type":"web_search"} tool).
include	Only "reasoning.encrypted_content" has an effect (adds encrypted_content to reasoning blocks when the provider returns it).
stream	Boolean. SSE with typed events.
anon_user_id	Optional end-user id: 1–128 printable ASCII characters, no `
fallbacks	Up to 10 {model} entries. Anthropic beta refusal fallback for Claude Fable 5; forwarded only on direct Anthropic routes.
venice_parameters	Subset listed above. Example: {"character_slug":"alan-watts","enable_web_search":"auto"}.

The body is permissive: other fields (instructions, metadata, parallel_tool_calls, n, stop, seed, prompt_cache_key, store, previous_response_id, background, text, user) are accepted without error but never reach inference (user still splits the error budget per value). Put system instructions in the input array instead of instructions.

Input items

Item	Shape	Handling
Message	{role, content} or {type:"message", role, content}	role: user / assistant / system / developer (developer becomes system). content is a string or an array of parts.
Function call	{type:"function_call", call_id, name, arguments}	Replayed as an assistant tool call.
Function output	{type:"function_call_output", call_id, output}	output may be a string, array, object, number, boolean, or null. input_image parts inside an array output are forwarded to the model as images.
Reasoning	{type:"reasoning", ...}	Accepted but discarded — reasoning is not carried between turns.
Item reference	{type:"item_reference", id}	Accepted but discarded (nothing is stored to reference).

Content parts: input_text, output_text (to replay assistant output), and input_image. input_image.image_url may be a URL string (OpenAI Responses style) or {url, detail}; detail (auto / low / high) may also sit on the part. Messages without type additionally accept Chat-style text and image_url parts. Image URLs get the same validation as on /chat/completions (public, no redirects, ≥ 64 px); failures → 400. Use a vision model: message images are not capability-checked on this endpoint (images inside a function_call_output on a non-vision model do return 400).

Tools

Tool	Effect
{"type":"function","function":{name, description, parameters, strict}}	Function calling. The flat OpenAI form {"type":"function","name":...,"parameters":...} is also accepted. Use a model with supportsFunctionCalling (not pre-checked on this endpoint, unlike chat).
{"type":"web_search"}	Forces Venice web search on (not auto). search_context_size / user_location are accepted but ignored.
{"type":"x_search", ...}	xAI native web + X search on models with supportsXSearch (Grok); ignored on other models. Optional filters: allowed_x_handles / excluded_x_handles (≤ 10 each), from_date, to_date, enable_image_understanding, enable_video_understanding.
code_interpreter, file_search, computer_use_preview, others	Accepted and dropped. Unknown tool types that carry a name are treated as function tools.

Response shape

{
  "id": "resp_chatcmpl-abc123",
  "object": "response",
  "created_at": 1735689600,
  "model": "zai-org-glm-5-1",
  "status": "completed",
  "output": [
    {"type": "reasoning", "id": "rs_1", "summary": ["I considered Rayleigh scattering..."]},
    {"type": "web_search_call", "id": "ws_1", "status": "completed"},
    {"type": "function_call", "id": "fc_1", "call_id": "call_abc", "name": "get_weather",
     "arguments": "{\"city\":\"Paris\"}", "status": "completed"},
    {"type": "message", "id": "msg_1", "status": "completed", "role": "assistant",
     "content": [{"type": "output_text", "text": "The sky is blue because... ^1^",
       "annotations": [{"type": "url_citation", "url": "https://example.com/rayleigh",
         "title": "Rayleigh scattering", "start_index": 27, "end_index": 30}]}]}
  ],
  "usage": {
    "input_tokens": 20,
    "input_tokens_details": {"cached_tokens": 8},
    "output_tokens": 80,
    "output_tokens_details": {"reasoning_tokens": 40},
    "total_tokens": 100
  }
}

• Non-streamed output order: reasoning → web_search_call → function_call(s) → message. The message block is omitted when the model returned only tool calls with no text.
• status is completed or incomplete. Errors before or during inference come back as HTTP errors (streaming uses response.failed).
• Incomplete responses keep their output and usage. When generation stops on max_output_tokens or a content filter, status: "incomplete", incomplete_details: {"reason": "max_output_tokens" | "content_filter"}, and message / function_call blocks carry status: "incomplete".
• input_tokens_details appears only when cached tokens are non-zero; output_tokens_details only when the provider reports reasoning tokens. There is no cost field (unlike /chat/completions).

Output block types

type	Purpose
reasoning	Reasoning from thinking models. summary[] holds text; encrypted_content appears only if you sent include: ["reasoning.encrypted_content"] and the provider returned encrypted reasoning. Sending it back in input has no effect.
message	Main text. content[].type === "output_text" with annotations[].
function_call	Tool call: name, JSON-string arguments, call_id. Answer with a function_call_output item with the same call_id.
web_search_call	Marker that Venice web search ran.

url_citation annotations are built only when the text contains single-index ^n^ markers — set venice_parameters.enable_web_citations: true to get them. Each annotation spans the marker itself; multi-index markers such as ^1,3^ are not annotated.

Streaming

With stream: true, events are event: <type> + data: {...} pairs; payloads carry type (equal to the event name) and an increasing sequence_number — except response.web_search.done, whose payload has type: "web_search_call", id, status, results and no sequence_number. Typical flow:

event: response.created                      # status: in_progress
event: response.web_search.done              # Venice-specific; only when search ran, carries results[{index,url,title,snippet}]
event: response.output_item.added            # item.type = reasoning
event: response.reasoning.delta
event: response.output_item.added            # item.type = message
event: response.content_part.added
event: response.output_text.delta            # repeated
event: response.output_item.added            # item.type = function_call
event: response.function_call_arguments.delta
event: response.output_item.done             # reasoning, then message (after content_part.done), then each function_call
event: response.completed                    # or response.incomplete, with the full response
data: [DONE]

• On an upstream failure you get response.failed (response.status: "failed", response.error: {code, message}) followed by data: [DONE].
• The final response.completed / response.incomplete payload differs slightly from a non-streamed response: annotations are always empty and function calls come after the message.
• include_search_results_in_stream has no effect here; search results always arrive in response.web_search.done.

Errors

Status	When
400	Invalid body, E2EE-capable model without enable_e2ee: false, invalid image, unsupported reasoning.effort for the model, context too long, max_output_tokens over the cap
401	Invalid API key or SIWX sign-in; also a model that requires a paid subscription
402	No credentials at all (x402 discovery body — not 401), insufficient balance, or API-key spend limit. x402: PAYMENT_REQUIRED body with topUpInstructions + siwxChallenge and a PAYMENT-REQUIRED header (see venice-x402)
403	Model blocked by the key's modelPrivacy, region, or provider restriction
404	Unknown model
422	Content-policy violation on an input image
429	Rate limited
500 / 503	Inference failed (upstream overloads and timeouts also surface as 500 here, not 429 / 504; retry with backoff) / model offline

The spec lists an X-Balance-Remaining header on x402 200 responses, but the server does not currently set it — poll GET /x402/balance/{walletAddress} instead. See venice-errors.

Migration notes (from /chat/completions)

• messages → input (the same role/content objects work; system prompts go in as role: "system" or "developer" items).
• max_tokens → max_output_tokens; reasoning_effort → reasoning.effort.
• Tool results → function_call_output items keyed by call_id.
• venice_parameters.character_slug, enable_web_search, enable_web_citations, enable_web_scraping, include_venice_system_prompt → pass inside venice_parameters (not as model suffixes).
• enable_x_search → add an {"type":"x_search"} tool instead.
• strip_thinking_response / disable_thinking → use reasoning.enabled: false.
• Structured output, audio / video / file inputs, seed / stop / n, logprobs, prompt-cache routing, and full E2EE → stay on /chat/completions.

Gotchas

• Unknown character_slug is not rejected here (chat returns 404). The request runs without the character, without your system messages, and without the Venice system prompt or web search. Validate slugs first with GET /characters/{slug} (venice-characters; Bearer key only — wallet callers can't, and should use /chat/completions, which returns 404 for unknown slugs).
• Reasoning items in input are discarded; there is no cross-turn reasoning carry-over on this endpoint.
• tool_choice objects must be {"type":"function","function":{"name":...}}; the flat {"type":"function","name":...} form fails validation.
• Stateless: previous_response_id is silently ignored, so omitting history silently loses context.