--- title: "List models" method: GET path: "/v1/models" tags: ["Models"] --- # List models `GET /v1/models` ## Request - Base URL: `https://api.tokenlab.sh` - URL: `https://api.tokenlab.sh/v1/models` - Auth: HTTP bearer Lists the currently available models. Use `view=compact` for model selection and `view=full` for the existing OpenAI-compatible discovery shape. Native API calls default to `full`; integrations may choose `compact` as their default. Non-chat recommendations are available through `recommended_for`. ## Query parameters - `provider` string - `tag` string - `category` 'chat' | 'embedding' | 'translation' | 'image' | 'video' | 'audio' | 'tts' | 'stt' | 'rerank' | '3d' | 'music' | 'decision' - `recommended_for` 'image' | 'video' | 'music' | '3d' | 'tts' | 'stt' | 'embedding' | 'rerank' | 'translation' | 'decision' - `view` 'compact' | 'full' ## Response `200` List of models - union - ModelsResponse - `object` 'list', required - `data` ModelListItem[], required - `id` string, required: Model identifier - `object` 'model', required - `created` integer, required: Unix timestamp - `owned_by` string, required: Model provider - `tokenlab` ModelListTokenLabExtension, required: TokenLab model discovery fields. Use the model details endpoint for the full supported request and pricing contract. - `aliases` string[], required - `deliveryAvailability` object: Current model availability by delivery tier; omitted when the source projection is unavailable. - `verified` boolean, required: Whether this model has eligible TokenLab Verified delivery supply. - `official` boolean, required: Whether this model has eligible Official delivery supply. - `operations` object - `pricing` ScalarPricing, required: One scalar price layer in USD. Token prices are per 1M tokens. - `input_per_1m` string, nullable, required: Price per 1M input tokens. Null for per-request pricing. - `output_per_1m` string, nullable, required: Price per 1M output tokens. Null for per-request pricing. - `per_request` string, nullable, required: Price per request. Null for per-token pricing. - `is_lock_price` boolean, required: Whether the model is priced per request. - `currency` 'USD', required - `official_pricing` ScalarPricing, required: One scalar price layer in USD. Token prices are per 1M tokens. - `input_per_1m` string, nullable, required: Price per 1M input tokens. Null for per-request pricing. - `output_per_1m` string, nullable, required: Price per 1M output tokens. Null for per-request pricing. - `per_request` string, nullable, required: Price per request. Null for per-token pricing. - `is_lock_price` boolean, required: Whether the model is priced per request. - `currency` 'USD', required - `capabilities` string[], required - `providers` string[] - `max_input_tokens` number, nullable, required - `max_output_tokens` number, nullable, required - `category` string, required - `pricing_unit` string, required - `cache_pricing` object, nullable: TokenLab Verified prompt-cache prices. Null or omitted when the model has no Verified supply (`deliveryAvailability.verified` is false). - `official_cache_pricing` object, nullable: Official prompt-cache prices. Null or omitted when none are published. - `has_complex_pricing` boolean, required - `pricing_summary` object, nullable - `agent_preferences` object - `lifecycle` object, required - `stage` 'active' | 'preview' | 'deprecated' | 'retired', required: Model lifecycle stage for public discovery and display. - `reason` string, nullable, required: Short model lifecycle explanation. - `replacement_model` string, nullable, required: Recommended replacement model when available. - `released_at` string, date-time, nullable, required: Official release date when available. - `deprecated_at` string, date-time, nullable, required: Official deprecation date when available. - `retired_at` string, date-time, nullable, required: Official retirement date when the model is no longer public-discoverable. - `sunset_at` string, date-time, nullable, required: Future sunset date for deprecated models. - `latest` boolean, required: Whether the model should receive a latest badge. - `latest_source` 'auto' | 'override' | 'none', required: How the latest badge was derived. - `latest_window_days` integer, nullable, required: Window used for automatic latest badges. - `commercial` object, required - `user_charge_policy` 'paid' | 'free', required: User billing policy for this model. - `free_reason` 'platform' | 'promotion' | 'null', nullable, required: Reason a model is free to users, if applicable. - `free_until` string, date-time, nullable, required: End time for a temporary free policy, if applicable. - `badges` object[], required: Display badges derived from lifecycle and commercial metadata. - `key` 'free' | 'latest' | 'preview' | 'deprecated' | 'retired', required - `tone` 'green' | 'blue' | 'amber' | 'red' | 'slate', required - `priority` integer, required - `tooltip` object, required - `key` string, required - `values` object, required - `request_format_summary` ModelListRequestFormatSummary, nullable - `public_operations` string[] - `request_endpoint` string, nullable - `request_endpoint_by_operation` object - CompactModelsResponse: Compact model-selection response used by TokenLab MCP and other agent integrations. - `object` 'list', required - `view` 'compact', required - `count` integer, required - `data` CompactModelListItem[], required - `id` string, required: Model identifier - `deliveryAvailability` object: Current model availability by delivery tier; omitted when the source projection is unavailable. - `verified` boolean, required: Whether this model has eligible TokenLab Verified delivery supply. - `official` boolean, required: Whether this model has eligible Official delivery supply. - `operations` object - `provider` string, required: Public model provider - `category` string, required - `capabilities` string[], required - `max_input_tokens` number, nullable, required - `max_output_tokens` number, nullable, required - `pricing` object, required - `unit` string, required - `currency` 'USD', required - `input_per_1m` string: TokenLab Verified price per 1M input tokens. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false). - `output_per_1m` string: TokenLab Verified price per 1M output tokens. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false). - `per_request` string: TokenLab Verified price per request. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false). - `min_price` string: Lowest TokenLab Verified price for a model with structured pricing. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false). - `max_price` string: Highest TokenLab Verified price for a model with structured pricing. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false). - `official_input_per_1m` string: Official price per 1M input tokens. Requests that Official delivers are billed at this price. - `official_output_per_1m` string: Official price per 1M output tokens. Requests that Official delivers are billed at this price. - `official_per_request` string: Official price per request. Requests that Official delivers are billed at this price. - `official_min_price` string: Lowest Official price for a model with structured pricing. - `official_max_price` string: Highest Official price for a model with structured pricing. - `has_complex_pricing` boolean, required - `status` string, required: Public model lifecycle stage. - `latest` boolean, required - `supported_operations` string[] - `request_endpoint` string - `recommendation` object - `preferred_rank` number, nullable, required - `success_rate_24h` number, nullable, required - `sample_count_24h` integer, required - `status` 'ready' | 'insufficient_samples', required ## Other responses - `400`: Bad Request - Invalid input - `401`: Unauthorized - Invalid or missing API key - `429`: Rate Limit Exceeded - `500`: Internal Server Error --- [API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)