> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-docs-revamp.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Chat Completions > Run text inference based on the supplied parameters. Supports multimodal inputs including text, images (image_url), audio (input_audio), video (video_url), and files (file) for compatible models. File inputs (PDF, DOCX, PPTX, XLSX, TXT, etc.) are automatically extracted to text before being sent to the model. Long running requests should use the streaming API by setting stream=true in your request. **Authentication:** This endpoint accepts either a Bearer API key or a `SIGN-IN-WITH-X` header for x402 wallet-based authentication. The legacy `X-Sign-In-With-X` header is also accepted during migration. When using x402, a `402 Payment Required` response indicates insufficient balance and includes top-up instructions. ## Postman Collection For additional examples, please see this [Postman Collection](https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-5a71391b-5dd8-4fe8-80be-197a958907fe?action=share\&creator=38652128\&ctx=documentation\&active-environment=38652128-ef110f4e-d3e1-43b5-8029-4d6877e62041). *** ## OpenAPI ````yaml POST /chat/completions openapi: 3.0.0 info: description: The Venice.ai API. termsOfService: https://venice.ai/legal/tos title: Venice.ai API version: '20260616.154934' x-guidance: >- Venice.ai is an OpenAI-compatible inference API supporting text, image, audio, and video generation. **Authentication options:** - API Key: Use Bearer token in Authorization header - x402 Wallet: Use USDC credits via EVM or Solana wallet (no account required) **For x402 wallet access:** 1. POST /x402/top-up without headers to get payment requirements 2. Choose one of the returned Base or Solana payment options and sign a USDC payment using the x402 SDK 3. POST /x402/top-up with PAYMENT-SIGNATURE header to add credits 4. Call any inference endpoint with SIGN-IN-WITH-X header **Pricing:** Prepaid credits consumed per request. Check /models for available models and their capabilities. servers: - url: https://api.venice.ai/api/v1 security: - BearerAuth: [] tags: - description: >- Generate speech/audio, transcribe audio, and manage asynchronous audio generation jobs. name: Audio - description: >- Given a list of messages comprising a conversation, the model will return a response. Supports multimodal inputs including text, images, audio (input_audio), and video (video_url) for compatible models. name: Chat - description: List and describe the various models available in the API. name: Models - description: Generate and manipulate images using AI models. name: Image - description: Generate videos using AI models. name: Video - description: List and retrieve character information for use in completions. name: Characters - description: >- Billing and usage analytics. **Beta**: This API is currently in beta and may be unstable. Endpoints, request/response schemas, and behavior may change without notice. name: Billing - description: Proxy JSON-RPC requests to blockchain nodes. Billed per credit. name: Crypto RPC - description: >- Wallet-based API access using the x402 protocol. No API key required — authenticate with an EVM or Solana wallet. **How it works:** 1. **Authenticate** — Send a `SIGN-IN-WITH-X` header (base64-encoded signed SIWX payload) with any request. EVM wallets sign an EIP-4361 SIWE message; Solana wallets sign the Solana SIWX message with Ed25519. See the `siwx` security scheme for the exact format. 2. **Top up** — `POST /x402/top-up` without a payment header returns an `accepts` array with Base and Solana USDC payment options. Choose one entry, sign it using the x402 SDK (`npm install x402`), and re-submit with the `PAYMENT-SIGNATURE` header (the legacy `X-402-Payment` and `X-PAYMENT` names are also accepted). 3. **Use any endpoint** — All inference endpoints (chat, image, audio, video, embeddings) accept `siwx` as an alternative to `BearerAuth`. Charges are deducted from your USDC credit balance. 4. **Monitor balance** — `GET /x402/balance/{walletAddress}` returns your current balance. The `X-Balance-Remaining` response header on inference calls also reports it. **Quick start (5 lines):** ``` import { VeniceClient } from '@venice-ai/x402-client' const venice = new VeniceClient(process.env.WALLET_KEY) await venice.topUp(10) // $10 USDC on a supported x402 rail const res = await venice.chat({ model: 'zai-org-glm-5-1', messages: [{ role: 'user', content: 'Hello!' }] }) ``` **Payment:** USDC on Base (chain ID 8453) or Solana mainnet. Minimum top-up: $5. Alternatively, stake DIEM tokens for daily credits (1 DIEM = $1/day). name: x402 externalDocs: description: Venice.ai API documentation url: https://docs.venice.ai paths: /chat/completions: post: tags: - Chat summary: /api/v1/chat/completions description: >- Run text inference based on the supplied parameters. Supports multimodal inputs including text, images (image_url), audio (input_audio), video (video_url), and files (file) for compatible models. File inputs (PDF, DOCX, PPTX, XLSX, TXT, etc.) are automatically extracted to text before being sent to the model. Long running requests should use the streaming API by setting stream=true in your request. **Authentication:** This endpoint accepts either a Bearer API key or a `SIGN-IN-WITH-X` header for x402 wallet-based authentication. The legacy `X-Sign-In-With-X` header is also accepted during migration. When using x402, a `402 Payment Required` response indicates insufficient balance and includes top-up instructions. operationId: createChatCompletion parameters: - description: >- Supported compression encodings (gzip, br). Only applied when stream is false. in: header name: Accept-Encoding required: false schema: example: gzip, br type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' responses: '200': description: OK headers: X-Balance-Remaining: description: >- Remaining x402 credit balance in USD after this request (only present for x402 auth). required: false schema: type: string example: '4.230000' Content-Encoding: description: The encoding used to compress the response schema: enum: - gzip - br type: string content: application/json: schema: type: object properties: choices: type: array items: type: object properties: finish_reason: type: string enum: - stop - length - tool_calls description: The reason the completion finished. example: stop index: type: integer description: The index of the choice in the list. example: 0 logprobs: type: object nullable: true properties: bytes: type: array items: type: number description: Raw bytes of the token example: - 104 - 101 - 108 - 108 - 111 logprob: type: number description: The log probability of this token example: -0.34 token: type: string description: The token string example: hello top_logprobs: type: array items: type: object properties: bytes: type: array items: type: number logprob: type: number token: type: string required: - logprob - token description: >- Top tokens considered with their log probabilities required: - logprob - token message: anyOf: - type: object properties: content: anyOf: - type: string title: String - type: array items: type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control text: type: string minLength: 1 description: >- The prompt text of the message. Must be at-least one character in length example: Why is the sky blue? title: Text Content Object type: type: string enum: - text title: Text Content String required: - text - type description: >- Text message type. Supports optional cache_control for prompt caching on supported providers. example: text: Why is the sky blue? type: text title: text title: Objects - nullable: true title: 'null' name: type: string nullable: true reasoning_content: type: string nullable: true reasoning_details: type: array items: type: object properties: data: type: string format: type: string id: type: string index: type: number text: type: string type: type: string required: - type description: >- Reasoning details returned by certain reasoning models that support this feature (e.g., Gemini 3 Pro). Not all reasoning models return this field. For multi-turn conversations with tool calls on supported models, pass back the reasoning_details exactly as received to preserve thought signatures. role: type: string enum: - assistant tool_calls: type: array nullable: true items: nullable: true required: - role description: >- The assistant message contains the response from the LLM. Must have either content or tool_calls. title: Assistant Message - type: object properties: content: type: string name: type: string nullable: true reasoning_content: type: string nullable: true role: type: string enum: - tool tool_call_id: type: string tool_calls: type: array nullable: true items: nullable: true required: - content - role - tool_call_id description: >- The tool message is a special message that is used to call a tool. It is not part of the conversation and is not visible to the user. title: Tool Message stop_reason: type: string nullable: true enum: - stop - length description: The reason the completion stopped. example: stop required: - finish_reason - index - logprobs - message description: >- A list of chat completion choices. Can be more than one if n is greater than 1. Certain models may not return this field under certain conditions. example: - finish_reason: stop index: 0 logprobs: null message: content: >- The sky appears blue because of the way Earth's atmosphere scatters sunlight. When sunlight reaches Earth's atmosphere, it is made up of various colors of the spectrum, but blue light waves are shorter and scatter more easily when they hit the gases and particles in the atmosphere. This scattering occurs in all directions, but from our perspective on the ground, it appears as a blue hue that dominates the sky's color. This phenomenon is known as Rayleigh scattering. During sunrise and sunset, the sunlight has to travel further through the atmosphere, which allows more time for the blue light to scatter away from our direct line of sight, leaving the longer wavelengths, such as red, yellow, and orange, to dominate the sky's color. reasoning_content: null role: assistant tool_calls: [] stop_reason: null created: type: integer description: The time at which the request was created. example: 1677858240 cost: type: object properties: diem: type: number minimum: 0 description: The DIEM-denominated portion of the request cost. example: 0 usd: type: number minimum: 0 description: >- The USD-denominated portion of the request cost. Bundled credits are included as USD-equivalent cost. example: 0.00042 required: - diem - usd description: The request cost split by billing currency. id: type: string description: The ID of the request. example: chatcmpl-abc123 model: type: string description: The model id used for the request. example: zai-org-glm-5-1 object: type: string enum: - chat.completion description: The type of the object returned. example: chat.completion prompt_logprobs: anyOf: - nullable: true title: 'null' - type: object additionalProperties: nullable: true - nullable: true title: 'null' description: Log probability information for the prompt. usage: type: object properties: completion_tokens: type: integer description: The number of tokens in the completion. example: 20 completion_tokens_details: type: object nullable: true properties: reasoning_tokens: type: integer description: >- Number of completion tokens consumed by reasoning/thinking output when the upstream model reports it. example: 32 description: >- Breakdown of completion tokens for providers that expose reasoning token accounting. prompt_tokens: type: integer description: The number of tokens in the prompt. example: 10 prompt_tokens_details: type: object nullable: true properties: cached_tokens: type: integer description: >- Number of prompt tokens that were served from cache (cache read) which may result in a discounted rate. example: 128 cache_creation_input_tokens: type: integer description: >- Number of prompt tokens that were written to cache (cache write). For some providers like Anthropic, this may be charged at a premium rate. example: 64 description: >- Breakdown of prompt tokens. Includes cached_tokens (cache read) and cache_creation_input_tokens (cache write) for models that support context caching. total_tokens: type: integer description: The total number of tokens used in the request. example: 30 required: - completion_tokens - prompt_tokens - total_tokens venice_parameters: type: object properties: enable_e2ee: type: boolean description: >- Did the request enable end-to-end encryption? Only applicable to E2EE-capable models. example: true enable_web_search: type: string enum: - auto - 'off' - 'on' description: Did the request enable web search? example: auto enable_web_citations: type: boolean description: Did the request enable web citations? example: true enable_web_scraping: type: boolean description: >- Did the request enable web scraping of URLs via Firecrawl? example: false include_venice_system_prompt: type: boolean description: Did the request include the Venice system prompt? example: true include_search_results_in_stream: type: boolean description: Did the request include search results in the stream? example: false return_search_results_as_documents: type: boolean description: >- Did the request also return search results as a tool-call documents block? example: true character_slug: type: string description: The character slug of a public Venice character. example: venice strip_thinking_response: type: boolean description: Did the request strip thinking response? example: true disable_thinking: type: boolean description: Did the request disable thinking? example: true web_search_citations: type: array items: type: object properties: content: type: string date: type: string title: type: string url: type: string required: - title - url description: Citations from web search results. example: - content: >- What's the scientific reason behind Earth's sky appearing blue to the human eye? And what's the real colour of the sky? Save 30% on the shop price when you subscribe to BBC Sky at Night Magazine today! In this article we'll look at the science behind why the sky is blue, or at least why it appears blue to our eyes. A beautiful blue sky is the sign of a pleasant day ahead. But what makes the sky appear blue? So, the sky appears blue because the molecules of nitrogen and oxygen in the atmosphere scatter light in short wavelengths towards the blue end of the visible spectrum. date: '2024-08-13T13:45:16.000Z' title: Why is the sky blue? | BBC Sky at Night Magazine url: >- https://www.skyatnightmagazine.com/space-science/why-is-the-sky-blue - content: >- It was around 1870 when the British physicist John William Strutt, better known as Lord Rayleigh, first found an explanation for why the sky is blue: Blue light from the Sun is scattered the most when it passes through the atmosphere. Published: January 20, 2025 8:34am EST · Daniel Freedman, University of Wisconsin-Stout · Daniel Freedman · Dean of the College of Science, Technology, Engineering, Mathematics & Management, University of Wisconsin-Stout · The answer has to do with molecules. It was around 1870 when the British physicist John William Strutt, better known as Lord Rayleigh, first found an explanation for why the sky is blue: Blue light from the Sun is scattered the most when it passes through the atmosphere. When the Sun is near the horizon, its light passes through a lot more of the atmosphere to reach the Earth’s surface than when it is directly overhead. The blue and green light is scattered so well that you can hardly see it. The sky is colored, instead, with red and orange light. date: '2025-04-16T16:55:11.000Z' title: Why is the sky blue? url: >- https://theconversation.com/why-is-the-sky-blue-246393 required: - enable_e2ee - enable_web_search - enable_web_citations - enable_web_scraping - include_venice_system_prompt - include_search_results_in_stream - return_search_results_as_documents - strip_thinking_response - disable_thinking description: Unique parameters to Venice's API implementation. required: - created - id - model - object - usage example: choices: - finish_reason: stop index: 0 logprobs: null message: content: >- The sky appears blue because of the way Earth's atmosphere scatters sunlight. When sunlight reaches Earth's atmosphere, it is made up of various colors of the spectrum, but blue light waves are shorter and scatter more easily when they hit the gases and particles in the atmosphere. This scattering occurs in all directions, but from our perspective on the ground, it appears as a blue hue that dominates the sky's color. This phenomenon is known as Rayleigh scattering. During sunrise and sunset, the sunlight has to travel further through the atmosphere, which allows more time for the blue light to scatter away from our direct line of sight, leaving the longer wavelengths, such as red, yellow, and orange, to dominate the sky's color. reasoning_content: null role: assistant tool_calls: [] stop_reason: null created: 1739928524 cost: diem: 0 usd: 0.00042 id: chatcmpl-a81fbc2d81a7a083bb83ccf9f44c6e5e model: zai-org-glm-5-1 object: chat.completion prompt_logprobs: null usage: completion_tokens: 146 completion_tokens_details: null prompt_tokens: 612 prompt_tokens_details: null total_tokens: 758 venice_parameters: enable_e2ee: true include_venice_system_prompt: true include_search_results_in_stream: false return_search_results_as_documents: false web_search_citations: [] enable_web_search: auto enable_web_scraping: false enable_web_citations: true strip_thinking_response: true disable_thinking: true character_slug: venice '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/DetailedError' '401': description: |- - Authentication failed - This model is only available to Pro users content: application/json: schema: $ref: '#/components/schemas/StandardError' '402': description: >- Payment or balance required. Response varies by authentication state: **API Key users:** Standard error response with `INSUFFICIENT_BALANCE` code. Top up your Venice balance at venice.ai. **Unauthenticated x402 discovery:** Structured x402 response with `x402Version`, `resource`, `accepts`, and `extensions["sign-in-with-x"]`. The `accepts` array advertises Base and Solana payment requirements. **Authenticated x402 wallet users with insufficient credit:** Structured response with `PAYMENT_REQUIRED` code containing: - `topUpInstructions`: Step-by-step guide to top up via x402 protocol - `supportedTokens` / `supportedChains`: Accepted payment methods - `siwxChallenge`: Fresh Sign-In-With-X challenge metadata The `PAYMENT-REQUIRED` header also contains a base64-encoded x402 protocol object with the payment requirements for programmatic discovery. headers: PAYMENT-REQUIRED: description: >- Base64-encoded JSON with x402 payment requirements. Present on x402 middleware 402 responses. Decode to choose and sign one accepted payment requirement programmatically. required: false schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/StandardError' - $ref: '#/components/schemas/X402InferencePaymentRequired' '415': description: Invalid request content-type content: application/json: schema: $ref: '#/components/schemas/StandardError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/StandardError' '500': description: Inference processing failed content: application/json: schema: $ref: '#/components/schemas/StandardError' '503': description: The model is at capacity. Please try again later. content: application/json: schema: $ref: '#/components/schemas/StandardError' '504': description: >- The request took too long to complete and was timed-out. For long-running inference requests, use the streaming API by setting stream=true in your request. content: application/json: schema: $ref: '#/components/schemas/StandardError' security: - BearerAuth: [] - siwx: [] components: schemas: ChatCompletionRequest: type: object properties: frequency_penalty: type: number maximum: 2 minimum: -2 default: 0 description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. logprobs: type: boolean description: >- Whether to include log probabilities in the response. This is not supported by all models. example: true top_logprobs: type: integer minimum: 0 description: >- The number of highest probability tokens to return for each token position. example: 1 max_completion_tokens: type: integer description: >- An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. max_temp: type: number minimum: 0 maximum: 2 description: Maximum temperature value for dynamic temperature scaling. example: 1.5 max_tokens: type: integer description: >- The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. Values of 0 or less are ignored and the model will use its default maximum. This value is now deprecated in favor of max_completion_tokens. messages: type: array items: anyOf: - type: object properties: content: anyOf: - type: string title: String - type: array items: oneOf: - type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control text: type: string minLength: 1 description: >- The prompt text of the message. Must be at-least one character in length example: Why is the sky blue? title: Text Content Object type: type: string enum: - text title: Text Content String required: - text - type description: >- Text message type. Supports optional cache_control for prompt caching on supported providers. example: text: Why is the sky blue? type: text title: text - type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control image_url: type: object properties: url: type: string description: >- The URL of the image. Can be a data URL with a base64 encoded image or a public URL. URL must be publicly accessible. Image must pass validation checks and be >= 64 pixels square. format: uri required: - url description: Object containing the image URL information title: Image URL Object type: type: string enum: - image_url required: - image_url - type description: >- Image URL message type. Supports optional cache_control for prompt caching on supported providers. title: image_url - type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control input_audio: type: object properties: data: type: string description: >- Base64-encoded audio data. Direct URLs are not supported for audio content. format: type: string enum: - wav - mp3 - aiff - aac - ogg - flac - m4a - pcm16 - pcm24 default: wav description: >- The format of the audio file. Common formats include wav, mp3, aac, ogg, flac, m4a. Defaults to wav. example: wav required: - data description: >- Object containing the base64-encoded audio data and format title: Input Audio Object type: type: string enum: - input_audio required: - input_audio - type description: >- Audio input message type for models that support audio analysis. Audio must be base64-encoded. example: input_audio: data: format: wav type: input_audio title: input_audio - type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control type: type: string enum: - video_url video_url: type: object properties: url: type: string description: >- The URL of the video. Can be a direct URL (including YouTube links for some providers), or a base64-encoded data URL (e.g., data:video/mp4;base64,...). Supported formats: mp4, mpeg, mov, webm. format: uri required: - url description: Object containing the video URL information title: Video URL Object required: - type - video_url description: >- Video URL message type for models that support video analysis. Supports both direct URLs and base64-encoded data URLs. example: type: video_url video_url: url: https://www.youtube.com/watch?v=dQw4w9WgXcQ title: video_url - type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control type: type: string enum: - file file: type: object properties: file_data: type: string description: >- The file content as a data URL (e.g., data:application/pdf;base64,...) or a publicly accessible URL. Supported formats: PDF, EPUB, DOCX, PPTX, XLSX, XLS, plain text, Markdown, CSV, JSON, and most source-code files (e.g., .py, .js, .ts, .c, .cpp, .java, .go, .rs, .ps1, .sh, .yaml, .sql). filename: type: string description: >- Optional filename for the file. Used for display purposes. example: document.pdf required: - file_data description: >- Object containing the file data and optional filename title: File Object required: - type - file description: >- File input message type for document processing. Supports PDF, EPUB, DOCX, PPTX, XLSX, plain text, and most source-code files (e.g., .py, .js, .ts, .c, .cpp, .java, .go, .rs, .ps1, .sh, .yaml, .sql). Files are extracted to text before being sent to the model. example: type: file file: file_data: data:application/pdf;base64,JVBERi0xLjQK... filename: document.pdf title: file title: Objects name: type: string nullable: true role: type: string enum: - user required: - content - role description: >- The user message is the input from the user. It is part of the conversation and is visible to the assistant. title: User Message - type: object properties: content: anyOf: - type: string title: String - type: array items: type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control text: type: string minLength: 1 description: >- The prompt text of the message. Must be at-least one character in length example: Why is the sky blue? title: Text Content Object type: type: string enum: - text title: Text Content String required: - text - type description: >- Text message type. Supports optional cache_control for prompt caching on supported providers. example: text: Why is the sky blue? type: text title: text title: Objects - nullable: true title: 'null' name: type: string nullable: true reasoning_content: type: string nullable: true reasoning_details: type: array items: type: object properties: data: type: string format: type: string id: type: string index: type: number text: type: string type: type: string required: - type description: >- Reasoning details returned by certain reasoning models that support this feature (e.g., Gemini 3 Pro). Not all reasoning models return this field. For multi-turn conversations with tool calls on supported models, pass back the reasoning_details exactly as received to preserve thought signatures. role: type: string enum: - assistant tool_calls: type: array nullable: true items: nullable: true required: - role description: >- The assistant message contains the response from the LLM. Must have either content or tool_calls. title: Assistant Message - type: object properties: content: type: string name: type: string nullable: true reasoning_content: type: string nullable: true role: type: string enum: - tool tool_call_id: type: string tool_calls: type: array nullable: true items: nullable: true required: - content - role - tool_call_id description: >- The tool message is a special message that is used to call a tool. It is not part of the conversation and is not visible to the user. title: Tool Message - type: object properties: content: anyOf: - type: string title: String - type: array items: type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control text: type: string minLength: 1 description: >- The prompt text of the message. Must be at-least one character in length example: Why is the sky blue? title: Text Content Object type: type: string enum: - text title: Text Content String required: - text - type description: >- Text message type. Supports optional cache_control for prompt caching on supported providers. example: text: Why is the sky blue? type: text title: text title: Objects name: type: string nullable: true role: type: string enum: - system required: - content - role description: >- The system message is a special message that provides context to the model. It is not part of the conversation and is not visible to the user. title: System Message - type: object properties: content: anyOf: - type: string title: String - type: array items: type: object properties: cache_control: type: object properties: ttl: type: string description: >- Optional TTL for extended cache duration. Beta feature requiring special header. example: 1h type: type: string enum: - ephemeral description: >- The type of cache control. Currently only "ephemeral" is supported. example: ephemeral required: - type description: >- Optional cache control for prompt caching on supported providers. example: type: ephemeral title: Cache Control text: type: string minLength: 1 description: >- The prompt text of the message. Must be at-least one character in length example: Why is the sky blue? title: Text Content Object type: type: string enum: - text title: Text Content String required: - text - type description: >- Text message type. Supports optional cache_control for prompt caching on supported providers. example: text: Why is the sky blue? type: text title: text title: Objects name: type: string nullable: true role: type: string enum: - developer required: - content - role description: >- The developer message provides high-level instructions to reasoning models (o1, codex). Semantically similar to system messages but specifically designed for reasoning model workflows. title: Developer Message minItems: 1 description: >- A list of messages comprising the conversation so far. Depending on the model you use, different message types (modalities) are supported, like text and images. Non-multimodal models reject image content. For vision models that support multiple images (supportsMultipleImages), images are preserved across all messages in the conversation history. For single-image vision models, only the last image-containing message retains its images. min_p: type: number minimum: 0 maximum: 1 description: >- Sets a minimum probability threshold for token selection. Tokens with probabilities below this value are filtered out. example: 0.05 min_temp: type: number minimum: 0 maximum: 2 description: Minimum temperature value for dynamic temperature scaling. example: 0.1 model: type: string description: >- The ID of the model you wish to prompt. May also be a model trait, or a model compatibility mapping. See the models endpoint for a list of models available to you. You can use feature suffixes to enable features from the venice_parameters object. Please see "Model Feature Suffix" documentation for more details. example: zai-org-glm-5-1 'n': type: integer default: 1 description: >- How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs. presence_penalty: type: number maximum: 2 minimum: -2 default: 0 description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. prompt_cache_key: type: string description: >- When supplied, this field may be used to optimize conversation routing to improve cache performance and thus reduce latency. example: random-string prompt_cache_retention: type: string enum: - default - extended - 24h description: >- OpenAI-compatible parameter to control prompt cache retention. "extended" or "24h" extends retention to 24 hours for supported models. example: 24h repetition_penalty: type: number minimum: 0 description: >- The parameter for repetition penalty. 1.0 means no penalty. Values > 1.0 discourage repetition. example: 1.2 reasoning: type: object properties: effort: type: string enum: - none - minimal - low - medium - high - xhigh - max description: >- Controls the reasoning effort level for supported models. Higher effort means more thorough reasoning but increased token usage. Defaults to the model configuration if not specified. example: medium summary: type: string enum: - auto - concise - detailed description: >- Controls whether and how the model generates a summary of its reasoning. "auto" lets the model decide, "concise" requests a brief summary, "detailed" requests a thorough summary. example: auto description: Configuration for reasoning behavior on supported models. reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh - max description: >- OpenAI-compatible parameter to control reasoning effort level for supported models. Takes precedence over reasoning.effort if both are provided. example: medium seed: type: integer minimum: 0 exclusiveMinimum: true description: >- The random seed used to generate the response. This is useful for reproducibility. example: 42 stop: anyOf: - type: string title: String - type: array items: type: string minItems: 1 maxItems: 4 title: Array of Strings - nullable: true title: 'null' description: >- Up to 4 sequences where the API will stop generating further tokens. Defaults to null. stop_token_ids: type: array items: type: number description: >- Array of token IDs where the API will stop generating further tokens. example: - 151643 - 151645 stream: type: boolean description: Whether to stream back partial progress. Defaults to false. example: true stream_options: type: object properties: include_usage: type: boolean description: Whether to include usage information in the stream. temperature: type: number minimum: 0 maximum: 2 description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: 0.7 top_k: type: integer minimum: 0 description: >- The number of highest probability vocabulary tokens to keep for top-k-filtering. example: 40 top_p: type: number minimum: 0 maximum: 1 description: >- An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. example: 0.9 user: type: string description: >- This field is discarded on the request but is supported in the Venice API for compatibility with OpenAI clients. fallbacks: type: array items: type: object properties: model: type: string required: - model maxItems: 10 description: >- Anthropic beta parameter for Claude Fable 5 server-side refusal fallback. Forwarded only for direct Anthropic routes; ignored for other providers. example: - model: claude-opus-4-8 store: type: boolean description: >- This field is accepted for OpenAI compatibility but is not used by Venice. verbosity: type: string enum: - low - medium - high - auto description: >- Controls the verbosity of the text response. Currently supported values are `low`, `medium`, and `high`. example: low text: type: object properties: verbosity: type: string enum: - low - medium - high - auto description: Controls the verbosity of the text response. example: low description: OpenAI-compatible text configuration parameter. include: type: array items: type: string description: >- OpenAI-compatible parameter specifying additional data to include in the response. metadata: type: object additionalProperties: type: string description: OpenAI-compatible metadata parameter for request tracking. venice_parameters: type: object properties: character_slug: type: string description: >- The character slug of a public Venice character. Discoverable as the "Public ID" on the published character page. strip_thinking_response: type: boolean default: false description: >- Strip blocks from the response. Applicable only to reasoning / thinking models. Also available to use as a model feature suffix. Defaults to false. example: false disable_thinking: type: boolean default: false description: >- On supported reasoning models, will disable thinking and strip the blocks from the response. Defaults to false. example: false enable_e2ee: type: boolean default: true description: >- Enable end-to-end encryption for E2EE-capable models. When true (default), E2EE is used if E2EE headers are present. When false, the model runs in TEE-only mode even if E2EE headers are present. Only applicable to models with E2EE capability. example: true enable_web_search: type: string enum: - auto - 'off' - 'on' default: 'off' description: >- Enable web search for this request. Defaults to off. On will force web search on the request. Auto will enable it based on the model's discretion. Citations will be returned either in the first chunk of a streaming result, or in the non streaming response. example: 'off' enable_web_scraping: type: boolean default: false description: >- Enable Venice web scraping of URLs in the latest user message using Firecrawl. Off by default. example: false enable_web_citations: type: boolean default: false description: >- When web search is enabled, this will request that the LLM cite its sources using a ^index^ or ^i,j^ superscript format (e.g., ^1^). Defaults to false. include_search_results_in_stream: type: boolean default: false description: >- Experimental feature - When set to true, the LLM will include search results in the stream as the first emitted chunk. Defaults to false. return_search_results_as_documents: type: boolean description: >- When set, search results are also surfaced in an OpenAI-compatible tool call named "venice_web_search_documents" to ease LangChain consumption. include_venice_system_prompt: type: boolean default: true description: >- Whether to include the Venice supplied system prompts along side specified system prompts. Defaults to true. enable_x_search: type: boolean default: false description: >- Enable xAI native search (web + X/Twitter) for supported models. When enabled, the model performs web and X searches server-side instead of Venice search augmentation. Only available on models with supportsXSearch capability (e.g., grok-4-20). Additional per-search charges apply (~$0.01/search). example: true description: >- Unique parameters to Venice's API implementation. Customize these to control the behavior of the model. parallel_tool_calls: type: boolean default: true description: Whether to enable parallel function calling during tool use. example: false response_format: oneOf: - type: object properties: json_schema: type: object additionalProperties: nullable: true type: type: string enum: - json_schema required: - json_schema - type additionalProperties: false description: >- The JSON Schema that should be used to validate and format the response. example: json_schema: properties: age: type: number name: type: string required: - name - age type: object type: json_schema title: json_schema - type: object properties: type: type: string enum: - json_object required: - type additionalProperties: false description: >- The response should be formatted as a JSON object. This is a deprecated implementation and the preferred use is json_schema. title: json_object - type: object properties: type: type: string enum: - text required: - type additionalProperties: false description: >- The response should be returned as plain text. This is the default behavior. title: text description: Format in which the response should be returned. tool_choice: anyOf: - type: object properties: function: type: object properties: name: type: string required: - name type: type: string required: - function - type - type: string tools: type: array nullable: true items: anyOf: - type: object properties: type: type: string enum: - web_search - x_search required: - type - type: object properties: function: type: object properties: description: type: string name: type: string parameters: type: object additionalProperties: nullable: true strict: type: boolean default: false description: >- If set to true, the model will follow the exact schema defined in the parameters field. Only a subset of JSON Schema is supported when strict is true. example: false required: - name id: type: string type: type: string required: - function description: >- A tool that can be called by the model. Currently, only functions are supported as tools. title: Tool Call description: >- A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. required: - messages - model additionalProperties: false DetailedError: type: object properties: details: type: object properties: {} description: Details about the incorrect input example: _errors: [] field: _errors: - Field is required error: type: string description: A description of the error required: - error StandardError: type: object properties: error: type: string description: A description of the error required: - error X402InferencePaymentRequired: anyOf: - type: object properties: x402Version: type: number description: x402 protocol version. example: 2 error: type: string description: Human-readable payment requirement message. example: Payment required resource: type: object properties: url: type: string description: Protected resource URL. example: https://api.venice.ai/api/v1/chat/completions description: type: string description: Human-readable resource description. example: Venice API mimeType: type: string description: Resource MIME type. example: application/json required: - url - description - mimeType additionalProperties: false accepts: type: array items: type: object properties: scheme: type: string enum: - exact description: x402 payment scheme. example: exact network: type: string description: Payment network for this requirement. example: solana asset: type: string description: USDC token address or mint for the selected network. example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v amount: type: string description: >- Required payment amount in base units (USDC has 6 decimals). example: '10000000' payTo: type: string description: Receiver wallet address for the selected network. example: 8qUL23aSj7mDWdoLMXGHFvnVCT9wd7jXcysiekroADEL maxTimeoutSeconds: type: number description: Maximum time allowed for payment settlement. example: 300 extra: type: object properties: {} description: >- Network-specific x402 metadata. Solana requirements include a feePayer. example: name: USD Coin version: '2' feePayer: BFK9TLC3edb13K6v4YyH3DwPb5DSUpkWvb7XnqCL9b4F required: - scheme - network - asset - amount - payTo - maxTimeoutSeconds - extra additionalProperties: false description: >- Protocol payment requirements. Clients should choose one entry, such as Base or Solana, and sign exactly that requirement. extensions: type: object properties: {} description: >- Protocol extensions. Inference 402 responses include `sign-in-with-x` with a SIWX challenge for wallet-credit authentication. authOptions: type: object properties: apiKey: type: object properties: header: type: string description: API key authentication header format. example: 'Authorization: Bearer YOUR_API_KEY' getKey: type: string description: Where to create or manage API keys. example: https://venice.ai/settings/api docs: type: string description: API key documentation URL. example: https://docs.venice.ai/api-reference required: - header - getKey - docs additionalProperties: false x402Wallet: type: object properties: header: type: string description: Header used for Sign-In-With-X wallet authentication. example: SIGN-IN-WITH-X legacyHeader: type: string description: Legacy Sign-In-With-X header accepted during migration. example: X-Sign-In-With-X topUp: type: string description: >- Endpoint used to discover and submit x402 top-up payments. example: POST /api/v1/x402/top-up docs: type: string description: x402 top-up API documentation URL. example: >- https://docs.venice.ai/api-reference/endpoint/x402/top-up required: - header - legacyHeader - topUp - docs additionalProperties: false required: - apiKey - x402Wallet additionalProperties: false required: - x402Version - resource - accepts - authOptions additionalProperties: false description: >- Returned when an inference request has no API key or wallet authentication. The JSON body includes x402 discovery requirements and authentication options. - type: object properties: error: type: string enum: - Payment required description: Error message indicating payment is required. code: type: string enum: - PAYMENT_REQUIRED description: Machine-readable error code. reason: type: string enum: - insufficient_balance description: Reason the x402-authenticated request could not proceed. message: type: string description: Human-readable context about the payment requirement. example: Insufficient x402 balance currentBalanceUsd: type: number description: Current x402 credit balance for the wallet. example: 0.01 minimumBalanceUsd: type: number description: Minimum x402 credit balance required before the request can run. example: 0.1 description: type: string description: Protected resource description. example: Venice API suggestedTopUpUsd: type: number description: Suggested amount to top up in USD. example: 10 minimumTopUpUsd: type: number description: Minimum allowed top-up amount in USD. example: 5 supportedTokens: type: array items: type: string description: List of supported token symbols for payment. example: - USDC supportedChains: type: array items: type: string description: List of supported top-up rails. example: - base - solana topUpInstructions: type: object properties: step1: type: string description: 'First step: get payment requirements.' example: >- POST /api/v1/x402/top-up with no payment header to get payment requirements step2: type: string description: 'Second step: sign the payment.' example: >- Choose a payment option from accepts and sign a USDC transfer authorization using the x402 SDK (createPaymentHeader) step3: type: string description: 'Third step: submit the payment.' example: >- POST /api/v1/x402/top-up with the signed PAYMENT-SIGNATURE header receiverWallet: type: string description: >- Legacy Base receiver wallet address. Prefer the selected accepts entry from /x402/top-up for network-specific payTo values. example: tokenAddress: type: string description: >- Legacy Base USDC token address. Prefer the selected accepts entry from /x402/top-up for network-specific assets. example: tokenDecimals: type: number description: Token decimal places. example: 6 network: type: string description: >- Legacy Base target network. Prefer the selected accepts entry from /x402/top-up for network-specific values. example: eip155:8453 minimumAmountUsd: type: number description: Minimum top-up amount in USD. example: 5 required: - step1 - step2 - step3 - receiverWallet - tokenAddress - tokenDecimals - network - minimumAmountUsd additionalProperties: false siwxChallenge: type: object properties: info: type: object properties: domain: type: string description: Domain for the SIWX challenge. example: api.venice.ai uri: type: string description: Resource URI for the challenge. example: https://api.venice.ai/api/v1/chat/completions version: type: string description: SIWX version. example: '1' nonce: type: string description: Unique nonce for replay protection. example: '{{nonce}}' issuedAt: type: string description: ISO timestamp when the challenge was issued. example: '2026-04-09T12:00:00.000Z' expirationTime: type: string description: ISO timestamp when the challenge expires. example: '2026-04-09T12:05:00.000Z' statement: type: string description: Human-readable statement for the signature. example: Sign in to Venice AI required: - domain - uri - version - nonce - issuedAt - expirationTime - statement additionalProperties: false supportedChains: type: array items: type: object properties: chainId: type: string description: Supported chain identity. example: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp type: type: string enum: - eip191 - eip1271 - ed25519 description: Signature type accepted for this chain. example: ed25519 required: - chainId - type additionalProperties: false description: Supported SIWX chains and signature types. required: - info - supportedChains additionalProperties: false required: - error - code - reason - suggestedTopUpUsd - minimumTopUpUsd - supportedTokens - supportedChains - topUpInstructions - siwxChallenge additionalProperties: false securitySchemes: BearerAuth: bearerFormat: JWT scheme: bearer type: http siwx: description: >- Wallet-based authentication using the x402 protocol (Sign-In-With-X). Supports EVM SIWE signatures on Base and Ed25519 signatures on Solana mainnet. **Header format:** Base64-encoded JSON object with the following fields: - `address` — EVM or Solana wallet address - `message` — Signed SIWX message. EVM wallets use EIP-4361 SIWE; Solana wallets use the Solana SIWX message format. - `signature` — Signature of the message, signed by the wallet's private key. EVM signatures are hex; Solana signatures may be base58 or base64. - `timestamp` — Unix timestamp in milliseconds - `chainId` — Chain identity. Use `8453`, `"8453"`, or `"eip155:8453"` for Base; use `"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"` for Solana. - `type` — Optional signature type. Use `"ed25519"` for Solana. Omitted means EVM/EIP-191 for backward compatibility. **EVM SIWE message fields:** - `domain`: `api.venice.ai` - `uri`: `https://api.venice.ai` - `version`: `"1"` - `chainId`: `8453` - `nonce`: Random 16-character hex string - `issuedAt` / `expirationTime`: ISO timestamps (recommended TTL: 10 minutes) - `statement`: `"Sign in to Venice API"` **Example (TypeScript):** ``` import { Wallet } from 'ethers' import { SiweMessage } from 'siwe' const wallet = new Wallet(PRIVATE_KEY) const msg = new SiweMessage({ domain: 'api.venice.ai', address: wallet.address, statement: 'Sign in to Venice API', uri: 'https://api.venice.ai', version: '1', chainId: 8453, nonce: crypto.randomUUID().replace(/-/g, '').slice(0, 16), issuedAt: new Date().toISOString(), expirationTime: new Date(Date.now() + 600000).toISOString() }) const signature = await wallet.signMessage(msg.prepareMessage()) const header = btoa(JSON.stringify({ address: wallet.address, message: msg.prepareMessage(), signature, timestamp: Date.now(), chainId: 8453 })) // Set header: SIGN-IN-WITH-X:
``` **Solana message fields:** The signed message starts with ` wants you to sign in with your Solana account:`, followed by the wallet address and the standard `URI`, `Version`, `Chain ID`, `Nonce`, `Issued At`, and optional `Expiration Time` fields. Use `type: "ed25519"` and `chainId: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"` in the encoded JSON payload. **SDK:** `npm install @venice-ai/x402-client` provides `VeniceClient` and `createAuthFetch` which handle this automatically. **Billing:** x402 users pay from a prepaid USDC credit balance. Top up via `POST /x402/top-up`. When balance is insufficient, endpoints return `402` with structured top-up instructions. in: header name: SIGN-IN-WITH-X type: apiKey ````