Venice.ai Transcriptions API

openapi: 3.2.0
info:
  title: Venice Ai Transcriptions 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 Transcriptions 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: Transcriptions
paths:
  /audio/transcriptions:
    post:
      description: 'Transcribes audio into the input language.


        **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: createTranscription
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequestSchema'
      security:
      - BearerAuth: []
      - siwx: []
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0.001'
          max: '10.00'
        protocols:
        - x402: {}
      summary: /api/v1/audio/transcriptions
      tags:
      - Transcriptions
      responses:
        '200':
          description: Transcription completed 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:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: The transcribed text
                  duration:
                    type: number
                    description: Duration of the audio in seconds
                  timestamps:
                    type: object
                    properties:
                      word:
                        type: array
                        items:
                          type: object
                          properties:
                            word:
                              type: string
                            start:
                              type: number
                            end:
                              type: number
                          required:
                          - word
                          - start
                          - end
                      segment:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                            start:
                              type: number
                            end:
                              type: number
                          required:
                          - text
                          - start
                          - end
                      char:
                        type: array
                        items:
                          type: object
                          properties:
                            char:
                              type: string
                            start:
                              type: number
                            end:
                              type: number
                          required:
                          - char
                          - start
                          - end
                    description: Timestamps for the transcription (only if timestamps=true)
                required:
                - text
                description: Transcription response
            text/plain:
              schema:
                type: string
                description: The transcribed text in plain text format
        '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'
        '413':
          description: The request payload is too large. Please reduce the size of your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayloadTooLargeError'
        '415':
          description: Invalid request content-type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '422':
          description: Validation error (e.g., zero-length audio)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '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:
    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
    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
    CreateTranscriptionRequestSchema:
      type: object
      properties:
        file:
          type: string
          description: 'The audio file object (not a base64 string). Supported formats: WAV, WAVE, FLAC, M4A, AAC, MP4, MP3, OGG, OGA, WEBM.'
          format: binary
        model:
          type: string
          enum:
          - nvidia/parakeet-tdt-0.6b-v3
          - openai/whisper-large-v3
          - fal-ai/wizper
          - elevenlabs/scribe-v2
          - stt-xai-v1
          default: nvidia/parakeet-tdt-0.6b-v3
          description: The model to use for transcription. See https://docs.venice.ai/models/overview for more information.
          example: openai/whisper-large-v3
        response_format:
          type: string
          enum:
          - json
          - text
          default: json
          description: 'The format of the transcript output, in one of these options: json, text.'
          example: json
        timestamps:
          type: boolean
          default: false
          description: Whether to include timestamps in the response.
          example: false
        language:
          type: string
          description: 'ISO 639-1 language code (e.g., "en", "es", "fr"). Optional - if not provided, the model will auto-detect the language. Note: Only supported by certain models (e.g., Whisper). Ignored by models that do not support language hints.'
          example: en
      additionalProperties: false
      description: Request to transcribe audio to text.
      example:
        file: '[audio file]'
        model: openai/whisper-large-v3
        response_format: json
        timestamps: false
    PayloadTooLargeError:
      type: object
      properties:
        code:
          type: string
          enum:
          - PAYLOAD_TOO_LARGE
          description: Machine-readable error code.
          example: PAYLOAD_TOO_LARGE
        error:
          type: string
          description: A description of the error
          example: File exceeds the maximum allowed size of 25 MB.
      required:
      - code
      - error
    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)