API Reference

One key, one base URL.

OpenAI-compatible chat, Anthropic-style messages, image generation, audio, and the full model catalog. Same key, same base URL.

Server checking…
Base URL https://api.freetheai.xyz/v1
Auth header Authorization: Bearer YOUR_API_KEY
GET /v1/health

The only public route. No key needed. Live data, straight from the API.

12 endpoints across 3 formats

Endpoints

Every route.#

Method Path Description
POST /​v1/​chat/​completions OpenAI-compatible chat, streaming, tool calling, and multi-turn conversations.POST /​v1/​messages Anthropic-compatible Messages route for Claude-style clients.POST /​v1/​responses Responses-style route. Same key, same model alias.POST /​v1/​images/​generations OpenAI-compatible image generation for supported image aliases.POST /​v1/​images/​edits OpenAI-compatible multipart image edits for supported image aliases.GET /​v1/​images/​generations/​{request_id} Poll async EVE image generation jobs.GET /​v1/​models Authenticated model list for normal clients.GET /​v1/​models/​full Expanded catalog with context, output, and access metadata.GET /​v1/​models/​leaderboard Site-key model leaderboard for public widgets.POST /​v1/​audio/​speech Text-to-speech for supported voice aliases.POST /​v1/​audio/​transcriptions Speech-to-text multipart uploads for supported voice aliases.GET /​v1/​health Public API health and catalog status.

Get a key#

Join Discord and run /signup. The bot opens a modal that asks for your use case, bot-disclosure answer, and a randomized human challenge. Send the issued key as a bearer token.

/signup Creates a key after the modal is completed. Existing keys are rejected; use /resetkey instead.
/checkin Required once per UTC day. Enter your existing API key and solve the randomized challenge before using the free API.
/resetkey Rotates a lost key after a real reset reason and challenge answer. Your account history stays linked.
Base URL
https://api.freetheai.xyz/v1

Header
Authorization: Bearer YOUR_API_KEY

Cross-compatible client formats#

FreeTheAi speaks three wire formats behind one base URL and one key. Pick the format your client expects; the model aliases never change between them.

OpenAI-compatibleChat completions, images, audio, and the model catalog. 21 of 22 documented clients use this format.
Anthropic-compatibleMessages route with system prompts, tool use, and the content blocks Claude-style clients expect.
Responses-styleResponses route for clients that speak that format.

Documented clients

The 22 setup guides cover chat completions (21), Anthropic-style messages (2), streaming (22), and tool calling (17). Same base URL and key for every one of them. Browse the setup guides.

OpenAI-compatible chat#

POST/v1/chat/completions

Point OpenAI-compatible clients at https://api.freetheai.xyz/v1. Use exact model aliases from /models.

Request body

model string required Exact model alias from /models, e.g. opc/deepseek-v4-flash-free.
messages array required Chat turns as { role, content } objects. Multi-turn conversations append to this list.
stream boolean optional When true, the response streams as server-sent events.
bash
curl https://api.freetheai.xyz/v1/chat/completions \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opc/deepseek-v4-flash-free",
    "messages": [
      { "role": "user", "content": "Write a tiny Flask route." }
    ],
    "stream": true
  }'
javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FREETHEAI_API_KEY,
  baseURL: "https://api.freetheai.xyz/v1"
});

const res = await client.chat.completions.create({
  model: "opc/deepseek-v4-flash-free",
  messages: [{ role: "user", content: "Reply with OK." }]
});

console.log(res.choices[0].message.content);

Response

Example response. The route mirrors the OpenAI chat completion shape.

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "opc/deepseek-v4-flash-free",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "OK." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15 }
}

Streaming

Send stream: true to receive Server-Sent Events instead of a single JSON body. Each event carries a chat completion chunk; the stream closes with data: [DONE].

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"OK."},"finish_reason":null}]}

data: [DONE]

Anthropic-style clients#

POST/v1/messages

Use /v1/messages for clients that expect Anthropic-style request bodies.

Request body

model string required Exact model alias from /models, e.g. opc/deepseek-v4-flash-free.
messages array required Anthropic-style content blocks. At least one user turn is required.
max_tokens integer optional Maximum tokens in the response. The example uses 256.
bash
curl https://api.freetheai.xyz/v1/messages \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opc/deepseek-v4-flash-free",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "Give me a short implementation plan." }
    ]
  }'

Response

Example response. The route mirrors the Anthropic message shape.

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "opc/deepseek-v4-flash-free",
  "content": [{ "type": "text", "text": "OK." }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 12, "output_tokens": 3 }
}

List models#

GET/v1/models

Use /v1/models for normal clients. Use /v1/models/full when you need tier and catalog metadata for a UI. The full catalog is a site-key endpoint, so public catalog clients use Bearer freetheai.xyz.

Response

One entry from the live catalog, abbreviated:

{
  "object": "list",
  "data": [
    {
      "id": "bbl/gemini-2.5-flash-lite",
      "object": "model",
      "owned_by": "gateway",
      "created": 0
    }
  ]
}

Client catalog

bash
curl https://api.freetheai.xyz/v1/models \
  -H "Authorization: Bearer $FREETHEAI_API_KEY"

Full catalog

bash
curl "https://api.freetheai.xyz/v1/models/full" \
  -H "Authorization: Bearer freetheai.xyz"

Images, audio, and responses#

These routes share the same base URL and bearer key as chat. Availability follows the catalog: use an alias that supports the route you are calling.

Images

POST/v1/images/generations
GET/v1/images/generations/​{request_id}
POST/v1/images/edits

OpenAI-compatible image generation and multipart edits for supported image aliases. Generation is async: the POST returns a request id, and the GET route polls the job until it completes.

Audio

POST/v1/audio/speech
POST/v1/audio/transcriptions

Text-to-speech for supported voice aliases, plus multipart speech-to-text uploads.

Responses

POST/v1/responses

Responses-style route for clients that speak that format. Same key, same model aliases.

Errors and rate limits#

Error shape

Most API errors use the OpenAI-style envelope. The type field is the machine-readable code you should branch on; message is the human-readable string.

{
  "error": {
    "message": "human readable message",
    "type": "machine_readable_type"
  }
}

Streaming requests can fail mid-stream after the SSE connection has already opened. In that case the API sends an error event followed by data: [DONE]:

data: {"error":{"message":"provider temporarily unavailable","type":"provider_error"}}

data: [DONE]

Some provider errors include a short public diagnostic id you can quote in Discord support, for example Error id: opc-xxxxxxxxxxxx.

Auth, check-in, and role gates

401 invalid_api_key Missing, invalid, revoked, or inactive key. Send the exact key from /signup as Authorization: Bearer YOUR_KEY with no quotes, markdown, or extra spaces.
403 daily_checkin_required Key is valid but the Discord owner has not checked in today. Run /checkin in the FreeTheAi Discord server.
403 model_access_denied Model is limited to Verified members, earned through active server participation.
403 discord_membership_required Key owner left the Discord. Rejoin with the same Discord account that owns the key.
403 user_paused Account paused by staff. Staff action required.
403 ip_blacklisted Source IP is banned. No client-side fix; staff action required.
403 client_signature_banned Banned client signature. Switch to a supported client; staff action may be required.

Request validation

400 invalid_request_error Bad JSON, missing field, unknown alias, or unsupported route. Common messages: invalid json payload, missing model, missing prompt, unknown aliased model, unsupported responses input shape, provider rejected the request payload. Use a model from GET /v1/models.
400 context_length_exceeded Prompt or request is too large. Reduce context, attachments, message history, or requested output tokens.
400 content_policy_violation Blocked by moderation/safety filters. Change the prompt content.
404 invalid_request_error Currently used for deferred video lookup when the request id is unknown.

Rate limits, daily caps, and concurrency

429 rate_limit_error Per-minute, daily-success cap, provider rate limit, or anti-abuse overlap block. Honor Retry-After when present and wait for the next UTC reset.
429 concurrency_limit_error Already running the maximum allowed parallel requests. Wait for one to finish.
429 glm_depleted GLM provider quota is depleted for the current 5-hour window. Retry later.
499 client_canceled Client disconnected while the request was still running. Keep the connection open until the response completes.

Provider and gateway

502 provider_error Provider call/read/translation failed. Retry, or try another model. If it persists, report the model and timestamp.
503 provider_unavailable Provider capacity is cooling down, busy, or temporarily unhealthy. Retry after Retry-After (typically 30s).
504 provider_timeout Provider took too long. Retry with smaller context/output or use streaming.
500 server_error Internal gateway error. Not user-fixable. Retry once, then report it.
503 server_error Internal dependency unavailable (DB, store, handler). Retry shortly.
503 discord_membership_error Discord membership/role lookup failed temporarily. Retry shortly.

Site-only catalog and stats endpoints

401 invalid_request_error Site-only endpoints (e.g. full catalog with metadata) need Authorization: Bearer freetheai.xyz. Common messages: invalid site catalog key, invalid site stats key.

Headers to respect

Rate, concurrency, and cooldown errors include machine-readable headers. Clients should branch on these rather than parsing the human message.

Retry-After Seconds to wait before retrying.
X-RateLimit-* Limit, Remaining, Reset for per-minute requests.
X-Concurrency-* Limit, Remaining, Reset for parallel requests.
X-DailyLimit-* Limit, Remaining, Reset for the daily success cap.

One-line user copy

401 invalid_api_key Your API key is missing or wrong.
403 daily_checkin_required Run /checkin in Discord.
403 model_access_denied This model is for Verified members.
400 invalid_request_error Your request body, model, or route is wrong.
400 context_length_exceeded Your prompt or context is too large.
400 content_policy_violation The request was blocked by moderation.
429 rate_limit_error You hit a rate limit, daily cap, or cooldown.
429 concurrency_limit_error Wait for your active request to finish.
502 provider_error Provider failed unexpectedly. Retry or try another model.
503 provider_unavailable Provider is temporarily unavailable.
504 provider_timeout Provider took too long.
500/503 server_error Gateway internal issue. Retry once.