Models & Aliases

Curated aliases only

model in any request must be a curated alias from the catalogue. A provider-native id (e.g. gpt-4o-2024-08-06, BAAI/bge-m3) is rejected:

404 not_found_error
code: model_not_found
param: model

There is no pinning to a provider id and no way to bypass the catalogue.

Aliases are visible in the portal under Models (with per-model pricing and capabilities), or programmatically via GET /v1/models.

Listing available models

GET /v1/models returns every enabled alias your key can call — rerank and video included — as a model card with OpenAI and OpenRouter fields and per-unit prices (full field list: List Models):

curl https://api.<domain>/v1/models \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "openai/text-embedding-3-small",
      "name": "openai/text-embedding-3-small",
      "object": "model",
      "created": 1756684800,
      "owned_by": "Token Factory",
      "context_length": 8191,
      "context_window": 8191,
      "architecture": { "modality": "text->embeddings", "input_modalities": ["text"], "output_modalities": ["embeddings"] },
      "pricing": { "unit": "token", "prompt": "0.00000002" },
      "top_provider": { "context_length": 8191, "is_moderated": false }
    }
  ]
}

The alias echo guarantee

Every JSON response echoes the alias you sent in model — including when the serving provider changed under failover:

{
  "model": "gpt-4o",
  "provider_metadata": {
    "provider": "openai",
    "actual_model": "gpt-4o-2024-08-06"
  }
}

• model — your alias, byte-identical.
• provider_metadata.actual_model — the provider's model id that served.
• provider_metadata.provider — the serving provider.

The same values ride in the X-TF-Model and X-TF-Actual-Model response headers on every response (JSON, streams, and audio bodies), so streaming and binary clients get one code path.

Deprecation lifecycle

{
  "provider_metadata": {
    "provider": "openai",
    "actual_model": "gpt-4o-2024-08-06",
    "deprecation": {
      "alias": "gpt-4o",
      "sunset": "2026-12-01T00:00:00Z",
      "replacement": "gpt-4o-2025",
      "message": "Use gpt-4o-2025 after the sunset date."
    }
  }
}

Clients should treat the header / provider_metadata.deprecation as the signal to migrate — the alias keeps working until sunset.

Related

• List Models endpoint
• API Versioning