> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Responses > **Beta**: This endpoint is currently in beta and may be unstable. Request/response schemas and behavior may change without notice. It is available to all API users. Create a model response in OpenAI's Responses API format. Works with every Venice text model and returns typed output items such as `reasoning`, `message`, and `function_call`. Set `stream: true` to receive Server-Sent Events. Most OpenAI models are forwarded to OpenAI's Responses API natively. Other models, and requests that use Venice features such as web search or characters, are translated through Chat Completions, where some Responses features are not supported. Send `x-venice-responses-mode: native` or `compat` to choose the mode, and read the `x-venice-responses-lane` response header to see which one served the request. Venice does not store responses, so send the full conversation in `input` on every request. E2EE-capable models are not supported on this endpoint; use `/api/v1/chat/completions` with the required E2EE headers instead. See the [Responses API guide](https://docs.venice.ai/guides/features/responses-api) for the features and limitations of each mode. **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. ## OpenAPI ````yaml POST /responses openapi: 3.0.0 info: description: The Venice.ai API. termsOfService: https://venice.ai/legal/tos title: Venice.ai API version: '20261009.214810' 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: >- Create vector embeddings from text. `input` must be a string or an array of strings. Token arrays are not supported. LangChain OpenAIEmbeddings must set `check_embedding_ctx_length=False` to send text instead of tiktoken IDs. name: Embeddings - description: >- Evaluate a state against typed questions and get structured answers (yes/no probabilities, option picks with distributions, rubric scores). **Beta**: This API is currently in beta and may be unstable. Request/response schemas and behavior may change without notice. name: Decisions - 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: /responses: post: tags: - Responses summary: /api/v1/responses description: >- **Beta**: This endpoint is currently in beta and may be unstable. Request/response schemas and behavior may change without notice. It is available to all API users. Create a model response in OpenAI's Responses API format. Works with every Venice text model and returns typed output items such as `reasoning`, `message`, and `function_call`. Set `stream: true` to receive Server-Sent Events. Most OpenAI models are forwarded to OpenAI's Responses API natively. Other models, and requests that use Venice features such as web search or characters, are translated through Chat Completions, where some Responses features are not supported. Send `x-venice-responses-mode: native` or `compat` to choose the mode, and read the `x-venice-responses-lane` response header to see which one served the request. Venice does not store responses, so send the full conversation in `input` on every request. E2EE-capable models are not supported on this endpoint; use `/api/v1/chat/completions` with the required E2EE headers instead. See the [Responses API guide](https://docs.venice.ai/guides/features/responses-api) for the features and limitations of each mode. **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: createResponse requestBody: content: application/json: schema: $ref: '#/components/schemas/ResponsesRequest' responses: '200': description: Successful response 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: application/json: schema: type: object properties: id: type: string description: Unique identifier for the response. example: resp_abc123 object: type: string enum: - response description: The object type. created_at: type: integer description: Unix timestamp of when the response was created. model: type: string description: The model used for the response. status: type: string enum: - completed - failed - in_progress - cancelled - incomplete description: The status of the response. incomplete_details: type: object properties: reason: type: string enum: - max_output_tokens - content_filter required: - reason description: >- Why generation ended before completion; partial output and usage are retained. output: type: array items: anyOf: - type: object properties: type: type: string enum: - reasoning id: type: string summary: type: array items: type: string encrypted_content: type: string required: - type - id title: Reasoning Output - type: object properties: type: type: string enum: - message id: type: string status: type: string enum: - completed - in_progress - failed - incomplete role: type: string enum: - assistant content: type: array items: type: object properties: type: type: string enum: - output_text text: type: string annotations: type: array items: type: object properties: type: type: string enum: - url_citation url: type: string title: type: string start_index: type: integer end_index: type: integer required: - type - url - start_index - end_index title: URL Citation Annotation required: - type - text title: Output Text required: - type - id - status - role - content title: Message Output - type: object properties: type: type: string enum: - function_call id: type: string call_id: type: string name: type: string namespace: type: string arguments: type: string status: type: string enum: - completed - in_progress - incomplete required: - type - id - call_id - name - arguments - status title: Function Call Output - type: object properties: type: type: string enum: - custom_tool_call id: type: string call_id: type: string name: type: string namespace: type: string input: type: string status: type: string enum: - completed - in_progress - incomplete required: - type - id - call_id - name - input - status - type: object properties: type: type: string enum: - tool_search_call id: type: string call_id: type: string minLength: 1 execution: type: string enum: - client arguments: type: object additionalProperties: nullable: true status: type: string enum: - completed - in_progress - incomplete required: - type - id - call_id - execution - arguments - status - type: object properties: type: type: string enum: - web_search_call id: type: string status: type: string enum: - completed required: - type - id - status title: Web Search Call Output description: The output items generated by the model. usage: type: object properties: input_tokens: type: integer input_tokens_details: type: object properties: cached_tokens: type: integer output_tokens: type: integer output_tokens_details: type: object properties: reasoning_tokens: type: integer total_tokens: type: integer required: - input_tokens - output_tokens - total_tokens description: Token usage statistics. title: Usage error: type: object properties: code: type: string message: type: string required: - code - message description: Error information if the response failed. title: Error required: - id - object - created_at - model - status - output description: Response from the Responses API endpoint. title: Responses API Response '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' '403': $ref: '#/components/responses/ApiKeyIpRestrictedError' '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' security: - BearerAuth: [] - siwx: [] components: schemas: ResponsesRequest: type: object properties: model: type: string description: >- The ID of the model to use. E2EE-capable models are not supported on /api/v1/responses; use /api/v1/chat/completions with the required E2EE headers instead. example: zai-org-glm-5-1 input: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: type: string enum: - message role: type: string enum: - user - assistant - system - developer content: anyOf: - type: string - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text text: type: string required: - type - text title: Input Text - type: object properties: type: type: string enum: - input_image image_url: anyOf: - type: string - type: object properties: url: type: string detail: type: string enum: - auto - low - high - original required: - url detail: type: string enum: - auto - low - high - original required: - type - image_url title: Input Image - type: object properties: type: type: string enum: - output_text text: type: string annotations: type: array items: nullable: true required: - type - text title: Output Text (for history) id: type: string status: type: string enum: - completed - in_progress - incomplete required: - type - role - content title: Input Message - type: object properties: role: type: string enum: - user - assistant - system - developer content: anyOf: - type: string - type: array items: anyOf: - oneOf: - type: object properties: type: type: string enum: - input_text text: type: string required: - type - text title: Input Text - type: object properties: type: type: string enum: - input_image image_url: anyOf: - type: string - type: object properties: url: type: string detail: type: string enum: - auto - low - high - original required: - url detail: type: string enum: - auto - low - high - original required: - type - image_url title: Input Image - type: object properties: type: type: string enum: - output_text text: type: string annotations: type: array items: nullable: true required: - type - text title: Output Text (for history) - type: object properties: type: type: string enum: - text text: type: string required: - type - text - type: object properties: type: type: string enum: - image_url image_url: anyOf: - type: string - type: object properties: url: type: string detail: type: string enum: - auto - low - high - original required: - url required: - type - image_url id: type: string status: type: string enum: - completed - in_progress - incomplete required: - role - content title: Input Message (Flexible) - type: object properties: type: type: string enum: - reasoning id: type: string nullable: true summary: type: array nullable: true items: anyOf: - type: string - type: object properties: type: type: string enum: - summary_text text: type: string required: - type - text content: anyOf: - type: string - type: array items: nullable: true - nullable: true title: 'null' - nullable: true title: 'null' encrypted_content: type: string nullable: true status: type: string nullable: true enum: - completed - in_progress required: - type title: Reasoning - type: object properties: type: type: string enum: - function_call id: type: string call_id: type: string name: type: string namespace: type: string arguments: type: string status: type: string enum: - completed - in_progress - incomplete required: - type - call_id - name - arguments title: Function Call - type: object properties: type: type: string enum: - function_call_output call_id: type: string output: anyOf: - type: string - type: array items: nullable: true - type: object additionalProperties: nullable: true - type: number - type: boolean - nullable: true title: 'null' - nullable: true title: 'null' required: - type - call_id - output title: Function Call Output - type: object properties: type: type: string enum: - item_reference id: type: string required: - type - id title: Item Reference - type: object properties: type: type: string enum: - custom_tool_call id: type: string call_id: type: string name: type: string namespace: type: string input: type: string status: type: string enum: - completed - in_progress - incomplete required: - type - call_id - name - input - type: object properties: type: type: string enum: - custom_tool_call_output call_id: type: string output: anyOf: - type: string - type: array items: nullable: true - type: object additionalProperties: nullable: true - type: number - type: boolean - nullable: true title: 'null' - nullable: true title: 'null' required: - type - call_id - output - type: object properties: type: type: string enum: - additional_tools role: type: string enum: - developer tools: type: array items: anyOf: - type: object properties: type: type: string enum: - function defer_loading: type: boolean function: type: object properties: name: type: string description: type: string parameters: type: object additionalProperties: nullable: true strict: type: boolean defer_loading: type: boolean required: - name required: - type - function title: Function Tool - type: object properties: type: type: string enum: - tool_search execution: type: string enum: - client description: type: string nullable: true parameters: type: object properties: type: type: string enum: - object required: - type required: - type - execution - parameters - type: object properties: type: type: string enum: - web_search search_context_size: type: string enum: - low - medium - high user_location: type: object properties: type: type: string enum: - approximate city: type: string region: type: string country: type: string timezone: type: string required: - type title: Web Search Tool - type: object properties: type: type: string enum: - x_search allowed_x_handles: type: array items: type: string maxItems: 10 excluded_x_handles: type: array items: type: string maxItems: 10 from_date: type: string to_date: type: string enable_image_understanding: type: boolean enable_video_understanding: type: boolean required: - type title: X Search Tool - type: object properties: type: type: string enum: - code_interpreter container: type: object properties: image: type: string required: - type title: Code Interpreter Tool - type: object properties: type: type: string enum: - file_search vector_store_ids: type: array items: type: string max_num_results: type: integer ranking_options: type: object properties: ranker: type: string score_threshold: type: number required: - type title: File Search Tool - type: object properties: type: type: string enum: - computer_use_preview display_width: type: integer display_height: type: integer environment: type: string required: - type title: Computer Use Tool - type: object properties: type: type: string required: - type title: Generic Tool title: Tool Definition id: type: string required: - type - tools title: Additional Tools - type: object properties: type: type: string enum: - tool_search_call id: type: string call_id: type: string minLength: 1 execution: type: string enum: - client arguments: type: object additionalProperties: nullable: true status: type: string enum: - completed - in_progress - incomplete required: - type - call_id - execution - arguments - type: object properties: type: type: string enum: - tool_search_output id: type: string call_id: type: string minLength: 1 execution: type: string enum: - client status: type: string enum: - completed tools: type: array items: anyOf: - type: object properties: type: type: string enum: - function defer_loading: type: boolean function: type: object properties: name: type: string description: type: string parameters: type: object additionalProperties: nullable: true strict: type: boolean defer_loading: type: boolean required: - name required: - type - function title: Function Tool - type: object properties: type: type: string enum: - tool_search execution: type: string enum: - client description: type: string nullable: true parameters: type: object properties: type: type: string enum: - object required: - type required: - type - execution - parameters - type: object properties: type: type: string enum: - web_search search_context_size: type: string enum: - low - medium - high user_location: type: object properties: type: type: string enum: - approximate city: type: string region: type: string country: type: string timezone: type: string required: - type title: Web Search Tool - type: object properties: type: type: string enum: - x_search allowed_x_handles: type: array items: type: string maxItems: 10 excluded_x_handles: type: array items: type: string maxItems: 10 from_date: type: string to_date: type: string enable_image_understanding: type: boolean enable_video_understanding: type: boolean required: - type title: X Search Tool - type: object properties: type: type: string enum: - code_interpreter container: type: object properties: image: type: string required: - type title: Code Interpreter Tool - type: object properties: type: type: string enum: - file_search vector_store_ids: type: array items: type: string max_num_results: type: integer ranking_options: type: object properties: ranker: type: string score_threshold: type: number required: - type title: File Search Tool - type: object properties: type: type: string enum: - computer_use_preview display_width: type: integer display_height: type: integer environment: type: string required: - type title: Computer Use Tool - type: object properties: type: type: string required: - type title: Generic Tool title: Tool Definition required: - type - call_id - execution - tools description: >- The input to generate a response for. Can be a simple string or an array of messages. instructions: type: string nullable: true description: System instructions for the model, applied before `input`. include: type: array items: type: string description: Additional response fields to include (OpenAI-compatible). max_output_tokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum number of tokens to generate. temperature: type: number minimum: 0 maximum: 2 description: Sampling temperature between 0 and 2. top_p: type: number minimum: 0 maximum: 1 description: Nucleus sampling parameter. 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 reasoning: type: object nullable: true properties: effort: type: string enum: - none - minimal - low - medium - high - xhigh - max description: Controls reasoning effort level for supported models. enabled: type: boolean description: >- Set to false to disable reasoning on supported models. Ignored when an effort level is provided. summary: type: string enum: - auto - concise - detailed description: Controls reasoning summary format. description: Reasoning controls for models that support reasoning. title: Reasoning Configuration parallel_tool_calls: type: boolean description: Whether the model may call more than one tool in a single turn. tools: type: array items: anyOf: - type: object properties: type: type: string enum: - function defer_loading: type: boolean function: type: object properties: name: type: string description: type: string parameters: type: object additionalProperties: nullable: true strict: type: boolean defer_loading: type: boolean required: - name required: - type - function title: Function Tool - type: object properties: type: type: string enum: - tool_search execution: type: string enum: - client description: type: string nullable: true parameters: type: object properties: type: type: string enum: - object required: - type required: - type - execution - parameters - type: object properties: type: type: string enum: - web_search search_context_size: type: string enum: - low - medium - high user_location: type: object properties: type: type: string enum: - approximate city: type: string region: type: string country: type: string timezone: type: string required: - type title: Web Search Tool - type: object properties: type: type: string enum: - x_search allowed_x_handles: type: array items: type: string maxItems: 10 excluded_x_handles: type: array items: type: string maxItems: 10 from_date: type: string to_date: type: string enable_image_understanding: type: boolean enable_video_understanding: type: boolean required: - type title: X Search Tool - type: object properties: type: type: string enum: - code_interpreter container: type: object properties: image: type: string required: - type title: Code Interpreter Tool - type: object properties: type: type: string enum: - file_search vector_store_ids: type: array items: type: string max_num_results: type: integer ranking_options: type: object properties: ranker: type: string score_threshold: type: number required: - type title: File Search Tool - type: object properties: type: type: string enum: - computer_use_preview display_width: type: integer display_height: type: integer environment: type: string required: - type title: Computer Use Tool - type: object properties: type: type: string required: - type title: Generic Tool title: Tool Definition description: A list of tools the model may call. tool_choice: anyOf: - type: string enum: - auto - type: string enum: - none - type: string enum: - required - type: object properties: type: type: string enum: - function - custom name: type: string namespace: type: string required: - type - name - type: object properties: type: type: string enum: - function function: type: object properties: name: type: string required: - name required: - type - function description: Controls which tool is called by the model. web_search: type: boolean description: Enable web search for this request. stream: type: boolean description: Whether to stream back partial progress. anon_user_id: type: string minLength: 1 maxLength: 128 pattern: ^[\x20-\x7E]+$ description: >- Optional identifier for the API customer's end user. Combined with the Venice user id when attributing the request to upstream providers. Distinct from the discarded OpenAI `user` field. Must be printable ASCII and must not contain `||`. example: end-user-123 venice_parameters: type: object properties: character_slug: type: string description: The character slug of a public Venice character. enable_e2ee: type: boolean description: >- Enable end-to-end encryption for E2EE-capable models. When true (default), E2EE is used if headers are present. When false, TEE-only mode is used. enable_web_search: type: string enum: - auto - 'off' - 'on' description: Enable web search for this request. enable_web_scraping: type: boolean description: Enable Venice web scraping of URLs in the latest user message. enable_web_citations: type: boolean description: Request that the LLM cite its sources. include_venice_system_prompt: type: boolean description: Whether to include the Venice supplied system prompts. include_search_results_in_stream: type: boolean description: Include search results in the stream as the first emitted chunk. description: >- Venice-specific options, such as web search, characters, and the Venice system prompt. title: Venice Parameters required: - model - input description: >- Request body for the Responses API endpoint. E2EE-capable models are not supported on /api/v1/responses; use /api/v1/chat/completions with the required E2EE headers instead. title: Responses API Request 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 ApiKeyIpRestrictedError: type: object properties: error: type: string enum: - >- This API key is restricted to configured IP addresses, and this request's source IP is not allowed description: A description of the error example: >- This API key is restricted to configured IP addresses, and this request's source IP is not allowed required: - error responses: ApiKeyIpRestrictedError: content: application/json: schema: $ref: '#/components/schemas/ApiKeyIpRestrictedError' description: >- This API key is restricted to configured IP addresses, and this request's source IP is not allowed 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.