venice-chat

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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. Auth is a Bearer API key or an x402 wallet (`SIGN-IN-WITH-X`); see [`venice-auth`](../venice-auth/SKILL.md).

## Use when

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

For the OpenAI Responses-style shape (typed `output[]` blocks), see [`venice-responses`](../venice-responses/SKILL.md). To pick a model, see [`venice-text-routing`](../venice-text-routing/SKILL.md).

## Minimal request

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

OpenAI SDK (Python) — Venice-only fields go in `extra_body`:

```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.chat.completions.create(
    model="zai-org-glm-5-1",
    messages=[{"role": "user", "content": "Summarize today's AI news."}],
    extra_body={"venice_parameters": {"enable_web_search": "auto", "include_venice_system_prompt": False}},
)
```

Response shape is the standard OpenAI `chat.completion` object (`id`, `object: "chat.completion"`, `created`, `model`, `choices[].message`, `choices[].finish_reason`, `usage`) plus:

- `cost: {usd, diem}` — the request's cost split by the currency it was charged in (bundled credits count as USD). `0` when the response has no output tokens (those responses are not billed). Omitted if the cost can't be computed, and currently also when the request was charged to earned credits.
- `venice_parameters` — the effective Venice settings, plus `web_search_citations[]` (an empty array when no search ran).
- `usage.prompt_tokens_details.{cached_tokens, cache_creation_input_tokens}` and `usage.completion_tokens_details.reasoning_tokens` when the provider reports them.

`choices[].finish_reason` is one of `stop`, `length`, `tool_calls`, or `content_filter`. `content_filter` is a `200` in which the model refused or the output was cut (e.g. a Claude refusal); it is not a `422`, so check for it before trusting `message.content`. Some providers block mid-stream instead; the stream then ends with an in-band error chunk (`type: "content_filter_error"`, `code: "content_blocked_by_provider"`) followed by `[DONE]`.

`system_fingerprint` is always stripped. With `stream: true`, responses come as SSE `data:` lines in `chat.completion.chunk` format.

## The request body

The top-level schema is **strict**: unknown top-level fields return `400`. (A few compatibility aliases are rewritten before validation: `input` → `messages`, `max_output_tokens` → `max_tokens`, `web_search: true|false` → `enable_web_search`, `promptCacheKey` → `prompt_cache_key`.)

### Core fields (OpenAI-compatible)

| Field | Notes |
|---|---|
| `model` | string — model ID, trait (e.g. `default`, `default_code`), or compatibility mapping. Required. Feature suffixes allowed (see below). Lookups also tolerate dots/underscores/spaces (`kimi k2.6` → `kimi-k2-6`) and a `venice-` prefix (for IDEs that hijack `claude-*` names). |
| `messages` | array of `system` / `developer` / `user` / `assistant` / `tool` messages. Required, min 1. Assistant messages with neither `content` nor `tool_calls` are silently dropped. |
| `temperature` (0–2), `top_p` (0–1), `top_k` (int ≥ 0), `min_p` (0–1), `min_temp`, `max_temp` (0–2) | sampling controls. Some models publish defaults in `model_spec.constraints` |
| `repetition_penalty` (≥ 0), `frequency_penalty`, `presence_penalty` (−2..2) | repetition controls |
| `max_completion_tokens` / `max_tokens` *(deprecated)* | integers. Output cap including reasoning tokens. Above the model's `model_spec.maxCompletionTokens` → `400` on models with an enforced API cap. `max_tokens ≤ 0` is ignored; `max_tokens` is ignored when `max_completion_tokens` is set |
| `n` | number of choices (default `1`; you pay for all choices) |
| `seed` | positive integer |
| `stop` / `stop_token_ids` | string or 1–4 strings / array of token IDs |
| `stream`, `stream_options.include_usage` | SSE streaming (Venice sends the usage chunk even without `include_usage` — see Streaming) |
| `response_format` | `{type:"json_schema", json_schema:{name, schema, strict}}` (preferred), `{type:"json_object"}`, or `{type:"text"}` |
| `tools`, `tool_choice`, `parallel_tool_calls` | function calling |
| `logprobs`, `top_logprobs` (int ≥ 0) | log-probabilities |
| `reasoning_effort` / `reasoning.effort` | `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`. `reasoning_effort` wins if both are set |
| `reasoning.enabled` | `false` disables reasoning on supported models. Ignored when an effort is set |
| `reasoning.summary` | `auto` \| `concise` \| `detailed` |
| `prompt_cache_key` | cache-routing hint. If omitted, Venice derives a stable key per API user |
| `prompt_cache_retention` | `default` \| `extended` \| `24h`. `extended` and `24h` extend retention to 24 hours on supported models |
| `verbosity` / `text.verbosity` | `low` \| `medium` \| `high` \| `auto` (both placements accepted). Non-reasoning OpenAI models accept only `medium` / `auto` (`400` otherwise) |
| `anon_user_id` | optional end-user identifier (see below) |
| `fallbacks` | up to 10 `{model}` entries. Anthropic beta parameter for Claude Fable 5 server-side refusal fallback. Forwarded only on direct Anthropic routes, ignored elsewhere |
| `include`, `metadata` | accepted for OpenAI compatibility, removed before validation and not forwarded |
| `user`, `store` | accepted and discarded (OpenAI compat). `user` is **not** an alias of `anon_user_id` |

**`anon_user_id`** — identifies *your* end user; Venice combines it with your Venice user id when attributing the request upstream. Trimmed (a blank value is treated as absent); 1–128 characters; printable ASCII only (`0x20`–`0x7E`); must not contain `||`. Violations → `400`. Also accepted on `/responses`.

### Capability gates (400 before inference)

| You send | Model must have (`model_spec.capabilities`) |
|---|---|
| `image_url` parts | `supportsVision` |
| `input_audio` parts | `supportsAudioInput` |
| `video_url` parts | `supportsVideoInput` |
| `tools`, `tool_choice`, `parallel_tool_calls: true` | `supportsFunctionCalling` |
| `response_format` other than `text` | `supportsResponseSchema` |
| `logprobs: true` or any `top_logprobs` | `supportsLogProbs` |

Each rejection is a `400` whose `issues[]` entry for that field gives the reason; read `issues`, not just the top-level `error`.

OpenAI reasoning models (e.g. `openai-gpt-52`) also reject `seed`, `stop`, `n ≠ 1`, and non-zero `presence_penalty` / `frequency_penalty` with `400` (the `issues[]` entry for that field reads `"<field> is not supported by this model"`).

### `venice_parameters` (Venice-only)

All optional. Unknown keys inside `venice_parameters` are dropped.

| Field | Type | Default | Effect |
|---|---|---|---|
| `character_slug` | string | — | Apply a published Venice character (the "Public ID" on its page). Unknown slug → `404`. See [`venice-characters`](../venice-characters/SKILL.md). |
| `strip_thinking_response` | bool | `false` | Strip reasoning from the response (`<think>` blocks and `reasoning_content`) on reasoning models. |
| `disable_thinking` | bool | `false` | Disable thinking on supported reasoning models and strip reasoning. On models that can't turn reasoning off, reasoning still runs (some drop to their lowest effort) but is stripped from the response; those reasoning tokens may still be billed. |
| `enable_e2ee` | bool | `true` | On E2EE-capable models, use E2EE when E2EE headers are present. `false` forces TEE-only mode. |
| `enable_web_search` | `"off"` / `"auto"` / `"on"` | `"off"` | Venice web search. `on` always searches; `auto` lets a classifier decide. |
| `enable_web_scraping` | bool | `false` | Scrape URLs found in the latest user message. When URLs are found, scraping replaces web search for that request. |
| `enable_web_citations` | bool | `false` | Ask the model to cite sources as `^1^` / `^1,3^`. |
| `include_search_results_in_stream` | bool | `false` | Experimental. Streaming only: emit a `choices: []` chunk carrying `venice_parameters.web_search_citations` at the end of the stream, before `data: [DONE]`. |
| `return_search_results_as_documents` | bool | — | Also surface search results as a synthetic tool call (see Web search). |
| `include_venice_system_prompt` | bool | `true` | Prepend Venice's system prompt to yours. Set `false` for full control. |
| `enable_x_search` | bool | `false` | xAI native web + X search on models with `supportsXSearch` (Grok). Ignored on other models. Billed per search (~$0.01). |

### Model feature suffixes

Some `venice_parameters` can be set on the `model` string — useful when the client (OpenAI SDK, LangChain, an IDE) can't send `venice_parameters`:

From veniceai/skills, MIT.

More from veniceai/skills