Venice.ai API

Last verified against Venice's public documentation, OpenAPI-derived skills, and model-lifecycle guidance: 2026-07-24.

Venice exposes an OpenAI-compatible API plus native endpoints for images, asynchronous media, document parsing, search, account administration, wallet payments, and crypto RPC. The API surface is stable under /api/v1, but the model catalog, capabilities, constraints, pricing, rate limits, and deprecations change frequently.

Non-negotiable operating rules

1. Do not guess model IDs, prices, voices, dimensions, durations, context limits, or rate limits. Query the live discovery endpoints before generating production code or making recommendations.
2. Match the request to the selected model's metadata. Inspect modelspec.capabilities, modelspec.constraints, model_spec.pricing, privacy, offline, beta, regionRestrictions, and deprecation.
3. Use traits for automatic upgrades; use fixed IDs for reproducibility. Resolve traits with /models/traits; never assume what a trait currently points to.
4. Use queue_id, not legacy queueid, for asynchronous audio and video requests.
5. Quote asynchronous media before queueing it. For music and video: quote -> queue -> retrieve -> complete.
6. Treat Alpha, Beta, Preview, and experimental endpoints as unstable. Validate the current OpenAPI schema before shipping or pinning generated types.
7. Never expose credentials or wallet private keys. Do not place API keys in browser bundles, logs, prompts, screenshots, or checked-in files.
8. Do not retry validation, authentication, entitlement, or media-type errors unchanged. Retry only transient failures, honoring Retry-After and rate-limit headers.

Base URL and authentication

https://api.venice.ai/api/v1

Choose one authentication mode per request:

Prefer Bearer authentication unless the product explicitly needs wallet-native billing. Current endpoint contracts prefer SIGN-IN-WITH-X; the legacy X-Sign-In-With-X name remains accepted during migration. For x402, use Venice's supported client or an x402 SDK rather than hand-rolling signatures. See [references/auth-admin-billing.md](references/auth-admin-billing.md).

Start every task with this decision flow

1. Choose the API surface

2. Discover a current model

curl -sS "https://api.venice.ai/api/v1/models?type=text" \
  -H "Authorization: Bearer $VENICE_API_KEY"

curl -sS "https://api.venice.ai/api/v1/models/traits?type=text" \
  -H "Authorization: Bearer $VENICE_API_KEY"

Valid discovery types currently include:

text, image, inpaint, upscale, video, music, tts, asr, embedding, all

For coding models, query type=text and filter modelspec.capabilities.optimizedForCode, or resolve the defaultcode trait when present. The catalog can add types or fields; treat the OpenAPI document and live response as authoritative.

Use the included helper for a compact, filtered view:

python scripts/discover_models.py --type text
python scripts/discover_models.py --type text --capability supportsFunctionCalling
python scripts/discover_models.py --type text --capability optimizedForCode --privacy private --json
python scripts/discover_models.py --type image --show-traits

See [references/models-and-routing.md](references/models-and-routing.md).

3. Validate the request against model_spec

For text models, check at least:

• availableContextTokens and maxCompletionTokens
• privacy, offline, beta, regionRestrictions, deprecation
• supportsFunctionCalling, supportsReasoning, supportsReasoningEffort
• supportsResponseSchema, supportsVision, supportsMultipleImages, maxImages
• supportsAudioInput, supportsVideoInput, supportsWebSearch, supportsXSearch
• supportsTeeAttestation, supportsE2EE, optimizedForCode

For media models, also validate prompt limits, aspect ratios, resolutions, durations, dimensions, step ranges, voices, reference-image counts, and model-specific feature flags.

4. Pick a stable or adaptive model reference

• Use a fixed model ID when output stability, evaluations, regression tests, or reproducibility matter.
• Use a trait such as default, fastest, defaultcode, defaultvision, defaultreasoning, or mostintelligent when automatic upgrades are desirable.
• Resolve the trait once at startup and cache the mapping briefly. Do not cache the entire catalog for days.
• Monitor model_spec.deprecation and model-deprecation response headers.

OpenAI SDK quick start

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VENICE_API_KEY"],
    base_url="https://api.venice.ai/api/v1",
)

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "system", "content": "Answer accurately and concisely."},
        {"role": "user", "content": "Explain zero-knowledge proofs."},
    ],
    max_completion_tokens=800,
    extra_body={
        "venice_parameters": {
            "include_venice_system_prompt": False,
        }
    },
)

print(response.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: "https://api.venice.ai/api/v1",
});

const response = await client.chat.completions.create({
  model: "default",
  messages: [{ role: "user", content: "Explain zero-knowledge proofs." }],
  max_completion_tokens: 800,
  // Venice extension; cast only if the SDK type does not yet include it.
  venice_parameters: { include_venice_system_prompt: false },
} as OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming & {
  venice_parameters: { include_venice_system_prompt: boolean };
});

console.log(response.choices[0]?.message.content);

OpenAI-compatible surfaces include chat completions, embeddings, image generations, TTS, transcription, and model listing. Native Venice endpoints generally require direct HTTP calls.

Chat-specific extensions

Pass Venice-only features in venice_parameters:

For current reasoning-capable models, prefer top-level reasoning: {"enabled": false} when reasoning must be disabled; reasoning.effort: "none" and veniceparameters.disablethinking remain model-dependent.

When the client cannot add venice_parameters, supported options may be encoded as a model suffix:

default:enable_web_search=on&enable_web_citations=true&include_venice_system_prompt=false

Do not encode enablee2ee or enablex_search as suffixes unless the current docs explicitly add support.

See [references/chat-completions.md](references/chat-completions.md).

Multimodal and file inputs

messages[].content can be an array of typed parts on compatible models:

• text
• image_url
• input_audio — inline base64, not an audio URL
• video_url
• file — public URL or base64 data URL; Venice extracts text before inference

A file block uses:

{
  "type": "file",
  "file": {
    "file_data": "data:application/pdf;base64,...",
    "filename": "report.pdf"
  }
}

Files are request-scoped, and extracted text counts against the model context window. For reusable extraction or token counting, use /augment/text-parser instead.

Function calling and agent loops

Before sending tools, require supportsFunctionCalling. Then:

1. Send tools and tool_choice with the conversation.
2. Execute every returned toolcall; paralleltool_calls may yield several at once.
3. Append the assistant tool-call message unchanged.
4. Append one role: "tool" message per result using the matching toolcallid.
5. Call the model again for the final response.
6. On providers that return opaque reasoning_details, round-trip that field verbatim in later turns. Never fabricate or normalize it.

For schema-constrained output, require supportsResponseSchema and prefer responseformat.type = "jsonschema" over legacy json_object.

Asynchronous audio and video invariant

Use the same model ID and queue_id throughout the job:

POST /{audio|video}/quote
POST /{audio|video}/queue       -> queue_id, sometimes download_url
POST /{audio|video}/retrieve    -> JSON status or binary media
POST /{audio|video}/complete    -> finalize and delete Venice-hosted media

• Poll at a reasonable interval; do not busy-loop.
• /retrieve may return binary media directly, or a JSON COMPLETED state that requires downloading a temporary download_url returned by /queue.
• deletemediaon_completion: true can combine retrieval and cleanup where supported.
• Download before calling /complete.

See [references/audio-api.md](references/audio-api.md) and [references/video-api.md](references/video-api.md).

Production error policy

Log a client correlation ID plus any X-Request-ID, CF-RAY, model-deprecation warning, balance, and rate-limit headers returned. Never log prompts, uploaded files, raw media, API keys, SIWE payloads, or wallet signatures unless the product's explicit privacy policy permits it.

See [references/production.md](references/production.md).

Reference map

• [references/models-and-routing.md](references/models-and-routing.md) — live catalog, traits, capabilities, privacy, pricing, deprecation, routing
• [references/chat-completions.md](references/chat-completions.md) — chat, Responses Alpha, multimodal/files, tools, reasoning, search, caching, characters
• [references/image-api.md](references/image-api.md) — generation, OpenAI compatibility, style references, edit, multi-edit, upscale, background removal
• [references/audio-api.md](references/audio-api.md) — TTS, transcription, async music/long audio
• [references/video-api.md](references/video-api.md) — quote/queue/retrieve/complete, reference media, transcription
• [references/platform-api.md](references/platform-api.md) — embeddings, augment tools, characters, crypto RPC
• [references/auth-admin-billing.md](references/auth-admin-billing.md) — Bearer, x402, API keys, limits, billing, usage
• [references/production.md](references/production.md) — errors, retries, streaming, observability, testing
• [references/official-sources.md](references/official-sources.md) — authoritative Venice resources used to maintain this skill

Before declaring an integration complete

• The current model was discovered rather than remembered.
• Required capabilities and constraints were checked.
• Fixed ID versus trait was chosen intentionally.
• Deprecation, offline, beta, region, and privacy fields were handled.
• Cost was estimated from live pricing or a media quote.
• API keys are server-side and scoped with an appropriate consumption limit.
• Retries are bounded and status-aware.
• Streaming parsers handle terminal and mid-stream errors.
• Async jobs persist both model and queue_id and clean up media.
• Binary versus JSON responses are distinguished by Content-Type.
• Logs retain request correlation metadata without sensitive content.
• Alpha/Beta/Preview behavior is feature-flagged or isolated behind an adapter.