> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# قائمة الشخصيات

> This is a preview API and may change. Returns a list of characters supported in the API, with filtering by search, tags, categories, model, and sort options.

## endpoint تجريبية

<Warning>
  هذه endpoint تجريبية وقد تخضع للتغيير.
</Warning>

## مجموعة Postman

للمزيد من الأمثلة، يرجى مراجعة [مجموعة Postman هذه](https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-b1bd9f3e-507b-46c5-ad35-be7419ea5ad3?action=share\&creator=38652128\&ctx=documentation\&active-environment=38652128-ef110f4e-d3e1-43b5-8029-4d6877e62041).


## OpenAPI

````yaml GET /characters
openapi: 3.0.0
info:
  description: The Venice.ai API.
  termsOfService: https://venice.ai/legal/tos
  title: Venice.ai API
  version: '20260622.204854'
  x-guidance: >-
    Venice.ai is an OpenAI-compatible inference API supporting text, image,
    audio, and video generation.


    **Authentication options:**

    - API Key: Use Bearer token in Authorization header

    - x402 Wallet: Use USDC credits via EVM or Solana wallet (no account
    required)


    **For x402 wallet access:**

    1. POST /x402/top-up without headers to get payment requirements

    2. Choose one of the returned Base or Solana payment options and sign a USDC
    payment using the x402 SDK

    3. POST /x402/top-up with PAYMENT-SIGNATURE header to add credits

    4. Call any inference endpoint with SIGN-IN-WITH-X header


    **Pricing:** Prepaid credits consumed per request. Check /models for
    available models and their capabilities.
servers:
  - url: https://api.venice.ai/api/v1
security:
  - BearerAuth: []
tags:
  - description: >-
      Generate speech/audio, transcribe audio, and manage asynchronous audio
      generation jobs.
    name: Audio
  - description: >-
      Given a list of messages comprising a conversation, the model will return
      a response. Supports multimodal inputs including text, images, audio
      (input_audio), and video (video_url) for compatible models.
    name: Chat
  - description: List and describe the various models available in the API.
    name: Models
  - description: Generate and manipulate images using AI models.
    name: Image
  - description: Generate videos using AI models.
    name: Video
  - description: List and retrieve character information for use in completions.
    name: Characters
  - description: >-
      Billing and usage analytics. **Beta**: This API is currently in beta and
      may be unstable. Endpoints, request/response schemas, and behavior may
      change without notice.
    name: Billing
  - description: Proxy JSON-RPC requests to blockchain nodes. Billed per credit.
    name: Crypto RPC
  - description: >-
      Wallet-based API access using the x402 protocol. No API key required —
      authenticate with an EVM or Solana wallet.


      **How it works:**

      1. **Authenticate** — Send a `SIGN-IN-WITH-X` header (base64-encoded
      signed SIWX payload) with any request. EVM wallets sign an EIP-4361 SIWE
      message; Solana wallets sign the Solana SIWX message with Ed25519. See the
      `siwx` security scheme for the exact format.

      2. **Top up** — `POST /x402/top-up` without a payment header returns an
      `accepts` array with Base and Solana USDC payment options. Choose one
      entry, sign it using the x402 SDK (`npm install x402`), and re-submit with
      the `PAYMENT-SIGNATURE` header (the legacy `X-402-Payment` and `X-PAYMENT`
      names are also accepted).

      3. **Use any endpoint** — All inference endpoints (chat, image, audio,
      video, embeddings) accept `siwx` as an alternative to `BearerAuth`.
      Charges are deducted from your USDC credit balance.

      4. **Monitor balance** — `GET /x402/balance/{walletAddress}` returns your
      current balance. The `X-Balance-Remaining` response header on inference
      calls also reports it.


      **Quick start (5 lines):**

      ```

      import { VeniceClient } from '@venice-ai/x402-client'

      const venice = new VeniceClient(process.env.WALLET_KEY)

      await venice.topUp(10) // $10 USDC on a supported x402 rail

      const res = await venice.chat({ model: 'zai-org-glm-5-1', messages: [{
      role: 'user', content: 'Hello!' }] })

      ```


      **Payment:** USDC on Base (chain ID 8453) or Solana mainnet. Minimum
      top-up: $5. Alternatively, stake DIEM tokens for daily credits (1 DIEM =
      $1/day).
    name: x402
externalDocs:
  description: Venice.ai API documentation
  url: https://docs.venice.ai
paths:
  /characters:
    get:
      tags:
        - Characters
        - Preview
      summary: /api/v1/characters
      description: >-
        This is a preview API and may change. Returns a list of characters
        supported in the API, with filtering by search, tags, categories, model,
        and sort options.
      operationId: listCharacters
      parameters:
        - schema:
            type: array
            items:
              type: string
              maxLength: 100
            maxItems: 20
            description: >-
              Filter by category names. Repeat the parameter for multiple
              values. Comma-separated values are also accepted.
            example:
              - roleplay
              - philosophy
          required: false
          name: categories
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Filter by adult content flag
            example: 'false'
          required: false
          name: isAdult
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Filter to only show characters using pro models
            example: 'false'
          required: false
          name: isPro
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Filter to only show web-enabled characters
            example: 'true'
          required: false
          name: isWebEnabled
          in: query
        - schema:
            type: integer
            minimum: 0
            exclusiveMinimum: true
            maximum: 100
            default: 50
            description: 'Number of characters to return (max: 100)'
            example: 50
          required: false
          name: limit
          in: query
        - schema:
            type: array
            items:
              type: string
              maxLength: 200
            maxItems: 20
            description: >-
              Filter by model ID(s). Repeat the parameter for multiple values.
              Comma-separated values are also accepted.
            example:
              - zai-org-glm-5-1
              - kimi-k2-6
          required: false
          name: modelId
          in: query
        - schema:
            type: integer
            nullable: true
            minimum: 0
            default: 0
            description: Number of characters to skip for pagination
            example: 0
          required: false
          name: offset
          in: query
        - schema:
            type: string
            maxLength: 200
            description: >-
              Search characters by name, description, or tags. Hashtag search is
              supported.
            example: assistant
          required: false
          name: search
          in: query
        - schema:
            type: string
            enum:
              - featured
              - highestRating
              - highlyRated
              - highlyRatedAndRecent
              - imports
              - mostRecent
              - ratingCount
            description: Sort results using a supported character discovery mode
            example: imports
          required: false
          name: sortBy
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: >-
              Sort order applied to the selected sort mode. Defaults to
              descending when omitted.
            example: desc
          required: false
          name: sortOrder
          in: query
        - schema:
            type: array
            items:
              type: string
              maxLength: 100
            maxItems: 20
            description: >-
              Filter by tag names. Repeat the parameter for multiple values.
              Comma-separated values are also accepted.
            example:
              - helpful
              - productivity
          required: false
          name: tags
          in: query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        adult:
                          type: boolean
                          description: Whether the character is considered adult content
                          example: false
                        author:
                          type: string
                          description: >-
                            Short anonymized identifier derived from the
                            character author
                          example: k3x9q
                        createdAt:
                          type: string
                          description: Date when the character was created
                          example: '2024-12-20T21:28:08.934Z'
                        description:
                          type: string
                          nullable: true
                          description: Description of the character
                          example: >-
                            Alan Watts (6 January 1915 – 16 November 1973) was a
                            British and American writer, speaker, and
                            self-styled "philosophical entertainer", known for
                            interpreting and popularizing Buddhist, Taoist, and
                            Hindu philosophy for a Western audience.
                        featured:
                          type: boolean
                          description: >-
                            Whether the character is featured in public
                            discovery surfaces
                          example: false
                        id:
                          type: string
                          description: Unique ID of the character
                          example: 2f460055-7595-4640-9cb6-c442c4c869b0
                        name:
                          type: string
                          description: Name of the character
                          example: Alan Watts
                        shareUrl:
                          type: string
                          nullable: true
                          description: Share URL of the character
                          example: https://venice.ai/c/alan-watts
                        photoUrl:
                          type: string
                          nullable: true
                          description: URL of the character photo
                          example: >-
                            https://outerface.venice.ai/api/characters/2f460055-7595-4640-9cb6-c442c4c869b0/photo
                        slug:
                          type: string
                          description: >-
                            Slug of the character to be used in the completions
                            API
                          example: alan-watts
                        stats:
                          type: object
                          properties:
                            averageRating:
                              type: number
                              description: Average rating for the character
                              example: 4.7
                            imports:
                              type: number
                              description: Number of imports for the character
                              example: 112
                            ratingCount:
                              type: number
                              description: Number of ratings for the character
                              example: 24
                            ratingSum:
                              type: number
                              description: Sum of all rating values for the character
                              example: 113
                            userRating:
                              type: number
                              nullable: true
                              description: >-
                                The authenticated user rating for the character
                                when available
                          required:
                            - averageRating
                            - imports
                            - ratingCount
                            - ratingSum
                            - userRating
                        tags:
                          type: array
                          items:
                            type: string
                          description: Tags associated with the character
                          example:
                            - AlanWatts
                            - Philosophy
                            - Buddhism
                            - Taoist
                            - Hindu
                        updatedAt:
                          type: string
                          description: Date when the character was last updated
                          example: '2025-02-09T03:23:53.708Z'
                        webEnabled:
                          type: boolean
                          description: Whether the character is enabled for web use
                          example: true
                        modelId:
                          type: string
                          description: API model ID for the character
                          example: venice-uncensored-1-2
                      required:
                        - adult
                        - author
                        - createdAt
                        - description
                        - featured
                        - id
                        - name
                        - shareUrl
                        - photoUrl
                        - slug
                        - stats
                        - tags
                        - updatedAt
                        - webEnabled
                        - modelId
                  object:
                    type: string
                    enum:
                      - list
                required:
                  - data
                  - object
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '500':
          description: An unknown error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
components:
  schemas:
    StandardError:
      type: object
      properties:
        error:
          type: string
          description: A description of the error
      required:
        - error
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````