venice-responses

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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`](../venice-chat/SKILL.md).

> **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`](../venice-chat/SKILL.md) — 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`](../venice-auth/SKILL.md).

## Minimal request

```bash
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):

```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 `||`. Distinct from `user`. |
| `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

```json
{
  "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},

From veniceai/skills, MIT.

More from veniceai/skills