AI Models

The AI Models endpoint returns the catalog of LLM models that can be used as the engine_model of an AI configuration. Use it to build a model picker or to validate a model id before calling POST /ais or PUT /ais/{id}.

Note

AI Implementation Hint

Always read the model id from GET /ai_models response rather than hard-coding it. The catalog can change over time. An id that is not in the list (and does not use the openai., gemini., or grok. prefix, or the openrouter.<author>/<slug> custom form) is rejected with HTTP 400 INVALID_ENGINE_MODEL when you create or update an AI. A custom OpenRouter model without an engine key (none sent and none stored) is rejected with HTTP 400 ENGINE_KEY_REQUIRED. A customendpoint.<model-id> model without engine_base_url is rejected with HTTP 400 ENGINE_BASE_URL_REQUIRED.

Get the model list

GET https://api.voipbin.net/v1.0/ai_models

Returns every available model in a single response. Pagination is not used: page_size and page_token are ignored and next_page_token is always an empty string. Logged-in users and accesskeys can call this endpoint. Direct (public token) access is not supported.

$ curl --location --request GET 'https://api.voipbin.net/v1.0/ai_models?token=<YOUR_AUTH_TOKEN>'

Response:

{
    "result": [
        {
            "id": "gemini.gemini-2.5-flash",
            "label": "Gemini 2.5 Flash",
            "vendor": "Google",
            "recommended": true,
            "tags": ["low-cost"],
            "description": "Fast, balanced model for most voice conversations.",
            "platform_managed": false,
            "key_mode": "own_or_default"
        },
        {
            "id": "anthropic.claude-sonnet-4.5",
            "label": "Claude Sonnet 4.5",
            "vendor": "Anthropic",
            "recommended": false,
            "tags": [],
            "description": "Balanced Claude model with strong instruction following.",
            "platform_managed": true,
            "key_mode": "platform"
        },
        {
            "id": "custom.openrouter",
            "label": "OpenRouter model (your OpenRouter key)",
            "vendor": "OpenRouter",
            "recommended": false,
            "tags": [],
            "description": "Enter any model supported by OpenRouter.",
            "platform_managed": false,
            "key_mode": "own_required",
            "model_id_prefix": "openrouter."
        }
    ],
    "next_page_token": ""
}

Model

  • id (String): The model identifier. Use it as engine_model in POST /ais and PUT /ais/{id}. Format: <provider>.<model>.

  • label (String): Human-readable model name for display.

  • vendor (String): The model vendor (e.g., Google, OpenAI, Anthropic). Use it to group models in a picker.

  • recommended (Boolean): true when the platform recommends this model as a starting point.

  • tags (Array of String): Model tags: low-cost, and tool-calling for a local model whose operator marked it as supporting tool calling. The tags are informational and are not enforced.

  • description (String): A short description of the model.

  • platform_managed (Boolean): true when the platform supplies the credentials for this model. It does not mean the model is served by a particular provider or routing. The engine_key of the AI is not needed: on create send an empty string, on update you may omit it (a stored key is kept but not used), and any value you send is ignored. false means you must provide your own provider key in engine_key. Prefer key_mode, which is more precise.

  • key_mode (String): How engine_key is handled. platform: the platform supplies access and engine_key is ignored. own_or_default: your engine_key is used, or the platform default key when it is empty. own_required: engine_key is mandatory (on update the stored key counts when you omit it).

  • model_id_prefix (String, Optional): Present only for the entry where you type the model ID yourself (the custom OpenRouter entry, prefix openrouter.). Send engine_model as this prefix followed by the model ID, for example openrouter.mistralai/mistral-large-2411. The id of this entry (custom.openrouter) cannot be used as engine_model directly.

See Engine Model for the provider prefixes and validation rules.

Local models

When the platform operator has registered self-hosted OpenAI-compatible models, they appear in the list with vendor Local, key_mode platform and an id of the form local.<endpoint>.<model>. The server address is never shown. engine_key is ignored for these models (on update you may omit it). When the operator has marked one local model as the default, it is the only model with recommended set to true. If no local model is registered, none is listed.

Custom endpoint models

A model on a server that you host is not listed in this catalog. Select it by setting engine_model to customendpoint.<model-id> and engine_base_url to the HTTPS address of your OpenAI-compatible server, and optionally engine_base_key. engine_key is not used for these models. The address and the key belong to the AI configuration that you create, are not shared with other customers, and the key is never returned. See Custom endpoint models for the URL rules, the key semantics and the errors.