Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Venice Ai Speech API
version: '20261012.214344'
termsOfService: https://venice.ai/legal/tos
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.'
description: 'Operations tagged Speech across 2 of this provider''s published API definitions: venice-ai-swagger.yaml, venice-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.venice.ai/api/v1
security:
- BearerAuth: []
tags:
- name: Speech
paths:
/audio/speech:
post:
description: 'Converts text to speech using various voice models and formats.
**Output formats:** Format support is model-specific. Read `model_spec.supported_formats` and `model_spec.default_format` from GET /models?type=tts. Omitting `response_format` uses the model default; requesting an unsupported format returns HTTP 400.
**Voice cloning:** Some TTS models (e.g. `tts-chatterbox-hd`) accept a cloned-voice handle in the `voice` field. Mint a handle by uploading a reference audio sample to POST /v1/audio/voices, then pass the returned `vv_` value as `voice` here paired with the same `model`. Supported voice-cloning models advertise the `voice_cloning` capability on GET /models?type=tts.
**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: createSpeech
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpeechRequestSchema'
security:
- BearerAuth: []
- siwx: []
x-payment-info:
price:
mode: dynamic
currency: USD
min: '0.001'
max: '10.00'
protocols:
- x402: {}
summary: /api/v1/audio/speech
tags:
- Speech
responses:
'200':
description: Audio content generated successfully
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:
audio/aac:
schema:
format: binary
type: string
audio/flac:
schema:
format: binary
type: string
audio/mpeg:
schema:
format: binary
type: string
audio/opus:
schema:
format: binary
type: string
audio/pcm:
schema:
format: binary
type: string
audio/wav:
schema:
format: binary
type: string
'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':
description: 'Unauthorized access
This API key is restricted to configured IP addresses, and this request''s source IP is not allowed'
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/StandardError'
- $ref: '#/components/schemas/ApiKeyIpRestrictedError'
'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'
servers:
- url: https://api.venice.ai/api/v1
components:
schemas:
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
CreateSpeechRequestSchema:
type: object
properties:
input:
type: string
minLength: 1
maxLength: 4096
description: The text to generate audio for. The maximum length is 4096 characters.
example: Hello, this is a test of the text to speech system.
language:
type: string
minLength: 2
maxLength: 32
description: 'Optional language hint. Accepted values are model-specific: Qwen 3 accepts full names (English, Chinese, ...); xAI/ElevenLabs accept ISO 639-1 codes (en, ja, ...); MiniMax accepts full names. Unsupported values are silently ignored. Omit to let the model auto-detect.'
example: English
model:
type: string
enum:
- tts-kokoro
- tts-qwen3-0-6b
- tts-qwen3-1-7b
- tts-xai-v1
- tts-inworld-1-5-max
- tts-chatterbox-hd
- tts-orpheus
- tts-elevenlabs-turbo-v2-5
- tts-minimax-speech-02-hd
- tts-gemini-3-1-flash
- tts-gradium-v1
default: tts-kokoro
description: The model ID of a Venice TTS model.
example: tts-xai-v1
prompt:
type: string
maxLength: 500
description: 'A style prompt to control the emotion and delivery of the speech. Supported by models advertising `supportsPromptParam` (currently Qwen 3 TTS). Ignored by other models. Examples: "Very happy.", "Sad and slow.", "Excited and energetic."'
example: Very happy.
response_format:
type: string
enum:
- mp3
- opus
- aac
- flac
- wav
- pcm
description: Requested audio output format. Supported formats and the default when omitted are model-specific; see `model_spec.supported_formats` and `model_spec.default_format` from GET /models?type=tts. An explicit unsupported format returns HTTP 400.
example: mp3
speed:
type: number
minimum: 0.25
maximum: 4
default: 1
description: The speed of the generated audio. Select a value from 0.25 to 4.0. 1.0 is the default.
example: 1
streaming:
type: boolean
default: false
description: Should the content stream back sentence by sentence or be processed and returned as a complete audio file.
example: true
temperature:
type: number
minimum: 0
maximum: 2
description: Sampling temperature for speech generation. Higher values produce more varied output. Supported by models advertising `supportsTemperatureParam` (Qwen 3, Orpheus, Chatterbox HD). Ignored by other models.
example: 0.9
top_p:
type: number
minimum: 0
maximum: 1
description: Nucleus sampling parameter. Supported by models advertising `supportsTopPParam` (currently Qwen 3 TTS). Ignored by other models.
example: 1
voice:
type: string
maxLength: 512
default: af_sky
description: 'The voice to use when generating the audio. The maximum length is 512 characters. Voices are model-specific: Kokoro (e.g. af_sky, af_bella, am_adam), Qwen 3 (e.g. Vivian, Serena, Dylan), xAI (26 voices, e.g. eve, ara, rex, sal, leo, luna, orion, carina), Orpheus (tara, leah, jess, leo, dan, mia, zac, zoe), Inworld (Craig, Ashley, ...), Chatterbox (Aurora, Blade, ...), ElevenLabs Turbo (Rachel, Aria, ...), MiniMax (WiseWoman, DeepVoiceMan, ...), Gradium (Emma, Kent, Mia, Maximilian, Valentina, Sergio, Elise, Leo, Alice, Davi — spanning en/de/es/fr/pt). You can also pass a cloned-voice handle (`vv_<id>`) returned by POST /v1/audio/voices to synthesize in a previously cloned voice; the handle must be paired with the same model used to create it. Models that advertise `supports_custom_voice_id` (e.g. ElevenLabs) additionally accept a raw provider Voice ID here. Using an incompatible voice returns a 400 error. Call GET /models/{id} to list voices for a specific model.'
example: af_sky
required:
- input
additionalProperties: false
description: Request to generate audio from text.
example:
input: Hello, welcome to Venice Voice.
model: tts-xai-v1
response_format: mp3
speed: 1
streaming: false
voice: af_sky
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: <RECEIVER_WALLET_ADDRESS>
tokenAddress:
type: string
description: Legacy Base USDC token address. Prefer the selected accepts entry from /x402/top-up for network-specific assets.
example: <USDC_TOKEN_ADDRESS>
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-09 12:00:00+00:00
expirationTime:
type: string
description: ISO timestamp when the challenge expires.
example: 2026-04-09 12:05:00+00:00
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
StandardError:
type: object
properties:
error:
type: string
description: A description of the error
required:
- error
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: <header>
```
**Solana message fields:** The signed message starts with `<domain> 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
externalDocs:
description: Venice.ai API documentation
url: https://docs.venice.ai
x-refined-from:
- venice-ai-swagger.yaml
- venice-ai-openapi.yml
x-provenance:
method: harvested
publisher: Venice.ai
source: https://docs.venice.ai/swagger.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)