Models

​

Overview

​

Compatibility

{
  "object": "list",
  "data": [ { /* model */ }, ... ]
}

{
  "id": "deepseek/deepseek-chat-v3-0324",
  "object": "model",
  "created": 1736966400,
  "owned_by": "deepseek"
}

​

Features

• Basic Mode: Standard OpenAI-compatible model listing
• Detailed Mode: Enhanced information with pricing and model descriptions

​

Query Parameters

• name — display name
• description — short model description
• context_length — max input tokens (if known)
• capabilities.vision — whether the model supports native image input
• 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

​

Authentication

• 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)

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1704067200,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model", 
      "created": 1704067200,
      "owned_by": "anthropic"
    }
  ]
}

​

Detailed Response

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1704067200,
      "owned_by": "openai",
      "name": "GPT-4o Mini",
      "description": "OpenAI's affordable and intelligent small model for fast, lightweight tasks",
      "context_length": 128000,
      "capabilities": { "vision": true },
      "pricing": {
        "prompt": 0.00015,
        "completion": 0.0006,
        "currency": "USD",
        "unit": "per_million_tokens"
      },
      "icon_url": "/icons/OpenAI.svg",
      "cost_estimate": { "cheap": true }
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1704067200,
      "owned_by": "anthropic",
      "name": "Claude 3.5 Sonnet",
      "description": "Anthropic's most intelligent model, combining top-tier performance with improved speed",
      "context_length": 200000,
      "capabilities": { "vision": false },
      "pricing": {
        "prompt": 0.003,
        "completion": 0.015,
        "currency": "USD", 
        "unit": "per_million_tokens"
      },
      "icon_url": "/icons/Anthropic.svg"
    }
  ]
}

​

Field Descriptions

​

Basic Fields (Always Present)

​

Enhanced Fields (Detailed Mode Only)

​

Pricing Object Structure

​

Usage Examples

​

Basic Request

curl "https://nano-gpt.com/api/v1/models"

​

Detailed Request

curl "https://nano-gpt.com/api/v1/models?detailed=true"

​

Detailed with Authentication

curl "https://nano-gpt.com/api/v1/models?detailed=true" \
  -H "Authorization: Bearer your_api_key_here"

​

Alternative API Key Header

curl "https://nano-gpt.com/api/v1/models?detailed=true" \
  -H "x-api-key: your_api_key_here"

​

Endpoint Variants

​

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.

curl -H "Authorization: Bearer $NANOGPT_API_KEY" \
  https://nano-gpt.com/api/v1/models

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.

curl https://nano-gpt.com/api/subscription/v1/models

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.

curl https://nano-gpt.com/api/paid/v1/models

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:

{ "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

• /api/v1/embedding-models - List all available embedding models with detailed information
• /api/v1/embeddings - Create embeddings using the available models
• /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. Image models used in the UI are covered by separate routes and/or the non-OpenAI UI endpoint GET /api/models.
• 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).