Quickstart

Make your first API call in five minutes — curl, Python, Node.js, or the OpenAI/Anthropic SDKs.

1. Get an API key

Sign in to the portal.
Open a project (or create one under Projects).
Create an API key. The plaintext key is shown once at creation — store it in a secret manager, not in code.

Keys are hierarchical (Organisation → Project → API key) and carry their own model allowlist, IP allowlist, plan, rate limit, and optional spend cap.

2. Your first chat completion

curl https://api.<domain>/v1/chat/completions \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.<domain>/v1",
    api_key=os.environ["TOKENFACTORY_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.<domain>/v1',
  apiKey: process.env.TOKENFACTORY_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.<domain>",  # note: no /v1 — the SDK appends it
    api_key=os.environ["TOKENFACTORY_API_KEY"],
)

message = client.messages.create(
    model="claude-sonnet",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)

3. What you get back

{
  "id": "chatcmpl-1",
  "object": "chat.completion",
  "created": 1724680001,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?", "refusal": null },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": { "prompt_tokens": 5, "completion_tokens": 9, "total_tokens": 14 },
  "provider_metadata": { "provider": "openai", "actual_model": "gpt-4o-2024-08-06" }
}

Two things to notice:

model is the alias you sent, even though the provider's own model id (gpt-4o-2024-08-06) actually served the request. That id is always in provider_metadata.actual_model.
provider_metadata is always present on every successful JSON body — you can code against it unconditionally.

4. Point an existing OpenAI integration at the gateway

The only two lines that change are base_url and api_key:

client = OpenAI(
    base_url="https://api.<domain>/v1",
    api_key=os.environ["TOKENFACTORY_API_KEY"],
)

The same is true for TypeScript, Go, and any OpenAI-compatible tool (LangChain, Vercel AI SDK, Cursor, etc.): set the base URL to https://api.<domain>/v1 and use a Token Factory key.

5. Try other modalities

Every modality follows the same pattern — alias in, standard body out:

Task	Endpoint	Guide
Chat with tools/vision	`POST /v1/chat/completions`	Chat Completions
Streaming	`stream: true` on chat	Streaming
Embeddings	`POST /v1/embeddings`	Embeddings
Image generation	`POST /v1/images/generations`	Image Generation
Speech to text	`POST /v1/audio/transcriptions`	Transcriptions
Text to speech	`POST /v1/audio/speech`	Text to Speech
Reranking	`POST /v1/rerank`	Rerank
Video generation	`POST /v1/videos` (async)	Videos: Create

Common first-call mistakes

Symptom	Cause	Fix
`404 model_not_found`	A provider-native id was sent (`gpt-4o-2024-08-06`) or the alias is not on your key's allowlist.	Use a curated alias from Models in the portal.
`401 invalid_api_key`	Key mistyped, revoked, or from another environment.	Re-copy the key; check you are on the right deployment.
`402 insufficient_funds`	The organisation wallet has no credit.	Top up in Billing, then retry.
`403 model_not_allowed`	The key's model allowlist excludes the alias.	Add the alias to the key (Settings → API keys).