> ## Documentation Index > Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt > Use this file to discover all available pages before exploring further. # Models > List available models with optional detailed information including pricing ## Overview The `/api/v1/models` endpoint provides a list of available text generation models. It supports optional detailed information including pricing data. The endpoint maintains full backwards compatibility while adding powerful new features. For non-text model catalogs, use the dedicated catalog endpoints: * [Image models](/api-reference/endpoint/image-models) * [Video models](/api-reference/endpoint/video-models) * [Audio models](/api-reference/endpoint/audio-models) * [Embedding models](/api-reference/endpoint/embedding-models) For API-only distillation metadata and filtering, see [Distillation Policy](/api-reference/miscellaneous/distillation-policy). ## Notable Model IDs (Examples) Model availability changes frequently. Use `GET /api/v1/models` as the authoritative source of callable IDs. Examples below use canonical IDs only; legacy aliases are intentionally omitted. * **OpenAI**: `openai/gpt-5.2`, `openai/gpt-5.2-codex` * **Anthropic**: `anthropic/claude-opus-4.6`, `anthropic/claude-opus-4.6:thinking`, `anthropic/claude-sonnet-4.6`, `anthropic/claude-sonnet-4.6:thinking` * **Google Gemini 3**: `google/gemini-3-flash-preview`, `google/gemini-3.1-pro-preview`, `gemini-3-pro-image-preview`, `google/gemini-3-flash-preview-thinking` * **xAI Grok**: `x-ai/grok-4.3`, `x-ai/grok-latest`, `x-ai/grok-4.20`, `x-ai/grok-4.20-multi-agent` * **Moonshot Kimi K2.5**: `moonshotai/kimi-k2.5`, `moonshotai/kimi-k2.5:thinking` * **Zhipu GLM 4.6 / 4.7**: `z-ai/glm-4.6`, `z-ai/glm-4.6:thinking`, `zai-org/glm-4.7`, `zai-org/glm-4.7:thinking` * **DeepSeek V3.2**: `deepseek/deepseek-v3.2`, `deepseek/deepseek-v3.2:thinking` * **Qwen3 Coder**: `qwen/qwen3-coder-next`, `qwen/qwen3-coder-plus`, `qwen/qwen3-coder-flash` * **NousResearch Hermes 4**: `nousresearch/hermes-4-405b`, `nousresearch/hermes-4-405b:thinking`, `nousresearch/hermes-4-70b` ## Compatibility Responses mirror OpenAI's Models API shape. All models endpoints return: ```json theme={null} { "object": "list", "data": [ { /* model */ }, ... ] } ``` Each model minimally includes: ```json theme={null} { "id": "openai/gpt-5.2", "object": "model", "created": 1736966400, "owned_by": "openai" } ``` ## Features * **Basic Mode**: Standard OpenAI-compatible model listing * **Detailed Mode**: Enhanced information with pricing and model descriptions ## Provider Selection Discovery Provider selection support and provider IDs are discovered via `GET /api/models/:canonicalId/providers`. See [Provider Selection](/api-reference/miscellaneous/provider-selection) for details. ## Query Parameters | Parameter | Type | Default | Description | | ---------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `detailed` | boolean | `false` | Returns detailed model information including pricing and capabilities | | `sort` | string | none | Values: `favorites`, `mostused`. Reorders the returned model list. Sorting only affects models that would already be visible to the caller. It does not add or hide models. | When `detailed=true`, additional fields may be included per model: * `name` — display name * `description` — short model description * `context_length` — max input tokens (if known) * `max_output_tokens` — max output tokens (if known) * `capabilities` — feature flags (see below) * `pricing.prompt` and `pricing.completion` — at-cost per-million-token pricing in USD * `pricing.unit` — `per_million_tokens` * `icon_url` — small icon representing the provider * `cost_estimate` — internal rollup used in UI for cost hints (for example `"$"`, `"$$"`, or an object) * `category` — optional category tag (for example `"flagship"`, `"mini"`, `"reasoning"`) * `distillationPolicy` — optional policy metadata indicating whether model outputs may be used for distillation or output-based training under NanoGPT's recorded model-license rules ### Sorting model lists `GET /api/v1/models` supports `sort=favorites` and `sort=mostused`. When `sort` is present, NanoGPT returns the same model list the caller would normally receive, but reordered by the selected ranking. Sorting only affects models that would already be visible to the caller. It does not add or hide models. * `sort=favorites`: Orders models by the authenticated account's recent model usage. * `sort=mostused`: Orders models by global completed model usage. * Unused or unranked models remain in the response after ranked models, in the normal catalog order. * `sort=favorites` requires a valid API key to personalize the order. If no valid API key is provided, it falls back to normal ordering. * `sort=mostused` does not require authentication. * Invalid `sort` values are ignored. * Can be combined with `detailed=true`. Examples: ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/v1/models?sort=favorites" ``` ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?sort=mostused" ``` ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/v1/models?detailed=true&sort=favorites" ``` ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?detailed=true&sort=mostused" ``` ### `capabilities` (detailed mode) Common capability flags: | Field | Type | Description | | --------------------- | ------- | ---------------------------------------- | | `vision` | boolean | Supports image inputs | | `reasoning` | boolean | Supports extended thinking/reasoning | | `tool_calling` | boolean | Supports function/tool calling | | `parallel_tool_calls` | boolean | Supports multiple tool calls in parallel | | `structured_output` | boolean | Supports structured/JSON output modes | | `pdf_upload` | boolean | Supports PDF/document inputs | ## Authentication Authentication is optional but enables user-specific pricing in detailed mode: | Header | Format | Required | Description | | --------------- | ------------------ | -------- | --------------------------------- | | `Authorization` | `Bearer {api_key}` | Optional | API key for user-specific pricing | | `x-api-key` | `{api_key}` | Optional | Alternative API key header | Notes: * Invalid or missing API keys still return a list of models. We simply omit user-specific pricing considerations in `detailed=true` mode. * With a valid key, the canonical `/api/v1/models` may apply your account’s subscription visibility preference (see Endpoint Variants). ## Response Formats ### Basic Response (Default) Standard OpenAI-compatible format without pricing information: ```json theme={null} { "object": "list", "data": [ { "id": "openai/gpt-5.2", "object": "model", "created": 1704067200, "owned_by": "openai" }, { "id": "anthropic/claude-opus-4.6", "object": "model", "created": 1704067200, "owned_by": "anthropic" } ] } ``` ### Detailed Response Enhanced format with model descriptions, context lengths, and pricing: ```json theme={null} { "object": "list", "data": [ { "id": "openai/gpt-5.2", "object": "model", "created": 1704067200, "owned_by": "openai", "name": "GPT-5.2", "description": "OpenAI's flagship general-purpose model", "context_length": 128000, "max_output_tokens": 16384, "capabilities": { "vision": true, "reasoning": false, "tool_calling": true, "parallel_tool_calls": true, "structured_output": true, "pdf_upload": true }, "pricing": { "prompt": 2.50, "completion": 10.00, "currency": "USD", "unit": "per_million_tokens" }, "icon_url": "/icons/OpenAI.svg", "cost_estimate": "$", "category": "flagship" }, { "id": "anthropic/claude-opus-4.6", "object": "model", "created": 1704067200, "owned_by": "anthropic", "name": "Claude Opus 4.5", "description": "Anthropic's top-tier model for deep reasoning and writing", "context_length": 200000, "max_output_tokens": 8192, "capabilities": { "vision": true, "reasoning": true, "tool_calling": true }, "pricing": { "prompt": 15.00, "completion": 75.00, "currency": "USD", "unit": "per_million_tokens" }, "icon_url": "/icons/Anthropic.svg", "cost_estimate": "$$$", "category": "reasoning" } ] } ``` ## Field Descriptions ### Basic Fields (Always Present) | Field | Type | Description | | ---------- | ------ | ------------------------------------------------------ | | `id` | string | Unique model identifier | | `object` | string | Always "model" for OpenAI compatibility | | `created` | number | Unix timestamp of response creation | | `owned_by` | string | Model provider (openai, anthropic, meta, google, etc.) | ### Enhanced Fields (Detailed Mode Only) | Field | Type | Description | | -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | `name` | string | Human-readable model name | | `description` | string | Detailed model description | | `context_length` | number | Maximum input tokens (null if not available) | | `max_output_tokens` | number | Maximum output tokens (null if not available) | | `capabilities` | object | Feature flags (e.g., `vision: boolean`) | | `pricing` | object | Pricing information object | | `icon_url` | string | Path/URL for a small provider icon | | `cost_estimate` | string or object | Internal hints (for example `"$"` / `"$$"` or `{ cheap: true }`) | | `category` | string | Optional category (e.g., `"flagship"`, `"mini"`, `"reasoning"`) | | `distillationPolicy` | object | Optional API-only distillation metadata. See [Distillation Policy](/api-reference/miscellaneous/distillation-policy). | ### Pricing Object Structure | Field | Type | Description | | ------------ | ------ | ------------------------------------- | | `prompt` | number | Cost per million input tokens in USD | | `completion` | number | Cost per million output tokens in USD | | `currency` | string | Always "USD" | | `unit` | string | Always "per\_million\_tokens" | ### Distillation Policy Where available, text model records include a `distillationPolicy` object with `status`, `label`, `basis`, `sourceUrl`, and `note`. This indicates whether model outputs may be used for model training, fine-tuning, distillation, or similar model-improvement workflows under NanoGPT's recorded interpretation of model licenses and provider terms. ```json theme={null} { "distillationPolicy": { "status": "allowed", "label": "License permits distillation", "basis": "permissive-open-weights", "sourceUrl": "https://example.com/license-or-terms", "note": "Short explanation of the policy signal." } } ``` Use the explore endpoints when you need to filter for distillation-allowed text models: ```http theme={null} GET /api/explore/text-models?distillation=allowed ``` ```http theme={null} GET /api/explore/search?type=text&q=qwen&distillation=allowed ``` The filter applies only to text models. Responses include `meta.distillation: "allowed"` when the filter is used and `meta.distillation: "all"` otherwise. Provider route policy can differ from model-level policy. Use `GET /api/models/:canonicalId/providers` and inspect each provider row's `distillationPolicy` before relying on a specific route for distillation. This metadata is informational and is not legal advice. Provider terms and model licenses can change, and licenses may impose attribution, naming, acceptable-use, or derivative-model restrictions even when distillation is allowed. ## Usage Examples ### Basic Request ```bash theme={null} curl "https://nano-gpt.com/api/v1/models" ``` ### Detailed Request ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?detailed=true" ``` ### Sort by Favorites ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/v1/models?sort=favorites" ``` ### Sort by Most Used ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?sort=mostused" ``` ### Detailed and Sorted ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/v1/models?detailed=true&sort=favorites" ``` ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?detailed=true&sort=mostused" ``` ### Detailed with Authentication ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?detailed=true" \ -H "Authorization: Bearer your_api_key_here" ``` ### Alternative API Key Header ```bash theme={null} curl "https://nano-gpt.com/api/v1/models?detailed=true" \ -H "x-api-key: your_api_key_here" ``` ## Endpoint Variants In addition to the canonical `/api/v1/models`, two filtered variants are available: ### 1) GET /api/v1/models (canonical) * Returns all visible text models (excludes internal free/helper selector models except `auto-model*`). * If your account has an active subscription and you have not enabled “Also show paid models”, the list is automatically restricted to only subscription-included models. * If you enable “Also show paid models” in settings, it returns the full set again. Examples: ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ https://nano-gpt.com/api/v1/models ``` ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/v1/models?detailed=true" ``` ### 2) GET /api/subscription/v1/models (subscription-only) * Always returns only models included in the NanoGPT subscription (equivalent to our `isTextEligible(modelId)` filter). * Ignores the user’s “Also show paid models” preference; it is always subscription-only. * Supports `?detailed=true` and API key–aware, at-cost pricing metadata. Examples: ```bash theme={null} curl https://nano-gpt.com/api/subscription/v1/models ``` ```bash theme={null} curl -H "x-api-key: $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/subscription/v1/models?detailed=true" ``` ### 3) GET /api/paid/v1/models (paid/extras) * Returns only models that are NOT part of the subscription (paid/premium/extras). * Supports `?detailed=true` and API key–aware, at-cost pricing metadata. Examples: ```bash theme={null} curl https://nano-gpt.com/api/paid/v1/models ``` ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://nano-gpt.com/api/paid/v1/models?detailed=true" ``` ### Choosing the Right Endpoint * Use `/api/subscription/v1/models` for curated lists guaranteed to be subscription-included (e.g., sub-only integrations). * Use `/api/paid/v1/models` to focus on paid or premium models. * Use `/api/v1/models` for the canonical list and let the account’s “Also show paid models” preference decide visibility. ## Errors and Limits * These endpoints typically return `200` with a list. If an invalid API key is provided, the list still returns and simply omits user-specific pricing considerations in `detailed=true` mode. * Standard CORS and rate limiting apply. In overload scenarios you may receive `429` with: ```json theme={null} { "code": "rate_limited", "message": "Rate limit exceeded" } ``` ## Backwards Compatibility * Default response format unchanged * All existing fields preserved * New fields are additive only * No breaking changes to existing integrations ## Related Endpoints * [Image models](/api-reference/endpoint/image-models) - List image model capabilities and supported parameters * [Video models](/api-reference/endpoint/video-models) - List video model capabilities and supported parameters * [Audio models](/api-reference/endpoint/audio-models) - List text-to-speech and speech-to-text models * [Embedding models](/api-reference/endpoint/embedding-models) - List embedding model dimensions, token limits, and pricing * [/api/v1/embeddings](/api-reference/endpoint/embeddings) - Create embeddings using the available embedding models * [Provider Selection](/api-reference/miscellaneous/provider-selection) - Discover model providers and set provider preferences * `/api/subscription/v1/models` - Subscription-included text models * `/api/paid/v1/models` - Paid or premium text models ## Notes * Scope: These endpoints list text-chat models. For image, video, audio, and embedding catalogs, use the dedicated model catalog pages linked above. * Fields are subject to change as new capabilities or providers are added. We aim to remain OpenAI-API compatible for basic consumers (`id`/`object`/`created`/`owned_by`). ## OpenAPI ````yaml GET /v1/models openapi: 3.1.0 info: title: NanoGPT API description: >- API documentation for the NanoGPT language, image, video, speech-to-text, and text-to-speech generation services license: name: MIT version: 1.0.0 servers: - url: https://nano-gpt.com/api description: NanoGPT API Server security: [] paths: /v1/models: get: description: >- List available models with optional detailed information including pricing parameters: - name: detailed in: query description: Returns detailed model information including pricing required: false schema: type: boolean default: false - name: sort in: query description: >- Reorders the returned model list without adding or hiding models. `favorites` orders by the authenticated account's recent model usage and requires a valid API key; without one it falls back to normal ordering. `mostused` orders by global completed model usage and does not require authentication. Unused or unranked models remain after ranked models in normal catalog order. Invalid values are ignored. required: false schema: type: string enum: - favorites - mostused example: favorites responses: '200': description: List of available models content: application/json: schema: $ref: '#/components/schemas/ModelsResponse' '400': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: ModelsResponse: type: object properties: object: type: string description: Type of object, always 'list' for the models response default: list data: type: array description: List of available models items: type: object properties: id: type: string description: Unique identifier for the model example: openai/gpt-5.2 object: type: string description: Type of object, always 'model' default: model created: type: integer description: Unix timestamp when the model was created owned_by: type: string description: Organization that owns the model example: openai name: type: string description: Human-readable model name (detailed mode only) example: GPT-4o Mini description: type: string description: Detailed model description (detailed mode only) example: >- OpenAI's affordable and intelligent small model for fast, lightweight tasks context_length: type: integer description: >- Maximum input tokens (detailed mode only, null if not available) example: 128000 pricing: type: object description: Pricing information object (detailed mode only) properties: prompt: type: number description: Cost per million input tokens in USD example: 0.00015 completion: type: number description: Cost per million output tokens in USD example: 0.0006 currency: type: string description: Always 'USD' default: USD unit: type: string description: Always 'per_million_tokens' default: per_million_tokens distillationPolicy: $ref: '#/components/schemas/DistillationPolicy' Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string DistillationPolicy: type: object description: >- API-only policy metadata indicating whether model or provider-route outputs may be used for model training, fine-tuning, distillation, or similar model-improvement workflows under NanoGPT's recorded model-license and provider-terms rules. properties: status: type: string description: Whether distillation is allowed under the current recorded rule set. enum: - allowed - disallowed - unknown example: allowed label: type: string description: Human-readable policy summary. example: License permits distillation basis: type: string description: Rule basis used to derive the policy status. enum: - deepseek-api-terms - permissive-open-weights - provider-output-use-terms - provider-output-use-restriction - closed-provider-restriction - provider-terms-unknown example: permissive-open-weights sourceUrl: type: string description: >- License or provider terms URL used as the policy source, when recorded. format: uri example: https://example.com/license-or-terms note: type: string description: Short explanation and caveats for the policy signal. example: Short explanation of the policy signal. securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-api-key ````