Venice.ai Embeddings API

openapi: 3.2.0
info:
  title: Venice Ai Embeddings 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 Embeddings 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:
- 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
paths:
  /embeddings:
    post:
      description: 'Create embeddings for the supplied input. `input` must be a string or an array of strings. Token arrays (integer IDs) are rejected with HTTP 400. LangChain `OpenAIEmbeddings` sends token arrays unless `check_embedding_ctx_length` is `False`. Wrappers that construct `OpenAIEmbeddings` without that flag, including gpt-researcher''s `openai` provider, still send token arrays.


        **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: createEmbedding
      parameters:
      - description: Supported compression encodings (gzip, br)
        in: header
        name: Accept-Encoding
        required: false
        schema:
          example: gzip, br
          type: string
      security:
      - BearerAuth: []
      - siwx: []
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0.001'
          max: '10.00'
        protocols:
        - x402: {}
      summary: /api/v1/embeddings
      tags:
      - Embeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmbeddingRequestSchema'
      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:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        embedding:
                          type: array
                          items:
                            type: number
                          description: The embedding vector
                        index:
                          type: integer
                          description: The index of this embedding in the list
                        object:
                          type: string
                          enum:
                          - embedding
                          description: The object type, which is always "embedding"
                      required:
                      - embedding
                      - index
                      - object
                    description: The list of embeddings generated by the model.
                  model:
                    type: string
                    description: The name of the model used to generate the embedding.
                  object:
                    type: string
                    enum:
                    - list
                    description: The object type, which is always "list"
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                        description: The number of tokens used by the prompt.
                      total_tokens:
                        type: integer
                        description: The total number of tokens used by the request.
                    required:
                    - prompt_tokens
                    - total_tokens
                    description: The usage information for the request.
                required:
                - data
                - model
                - object
                - usage
                example:
                  data:
                  - embedding:
                    - 0.0023064255
                    - -0.009327292
                    - 0.015797377
                    index: 0
                    object: embedding
                  model: text-embedding-bge-m3
                  object: list
                  usage:
                    prompt_tokens: 8
                    total_tokens: 8
        '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'
        '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:
    CreateEmbeddingRequestSchema:
      type: object
      properties:
        dimensions:
          type: integer
          minimum: 1
          description: The number of dimensions the resulting output embeddings should have.
        encoding_format:
          type: string
          enum:
          - float
          - base64
          default: float
          description: The format to return the embeddings in. Can be either `float` or `base64`.
          example: float
        input:
          description: Input text to embed, encoded as a string or array of strings. To embed multiple inputs in a single request, pass an array of strings. The input must not exceed the max input tokens for the model (8192 tokens), cannot be an empty string, and any array must contain 2048 items or less. Token arrays are not supported and return HTTP 400. LangChain OpenAIEmbeddings sends token arrays unless you set check_embedding_ctx_length=False.
          anyOf:
          - description: The string that will be turned into an embedding. Cannot be an empty string.
            example: This is a test.
            minLength: 1
            title: string
            type: string
          - description: The array of strings that will be turned into an embedding. Array must contain 2048 items or less.
            example:
            - This is a test.
            items:
              type: string
            maxItems: 2048
            minItems: 1
            title: array
            type: array
          example: The quick brown fox jumped over the lazy dog
        model:
          anyOf:
          - type: string
          - type: string
            enum:
            - text-embedding-bge-m3
            - text-embedding-bge-en-icl
            - text-embedding-qwen3-8b
            - text-embedding-qwen3-0-6b
            - text-embedding-multilingual-e5-large-instruct
            - text-embedding-3-small
            - text-embedding-3-large
            - gemini-embedding-2-preview
            - text-embedding-nemotron-embed-vl-1b-v2
          description: ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.
          example: text-embedding-bge-m3
        user:
          type: string
          description: This is an unused parameter and is discarded by Venice. It is supported solely for API compatibility with OpenAI.
      required:
      - input
      - model
      additionalProperties: false
      description: Create embeddings for the supplied input.
      example:
        encoding_format: float
        input: The quick brown fox jumped over the lazy dog
        model: text-embedding-bge-m3
    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
    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
  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: <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)