API Docs

One key, one base URL.

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

12 endpoints 3 formats free tier
Getting started

Connect in seconds.

Base URL https://api.freetheai.xyz/v1
Auth header Authorization: Bearer YOUR_API_KEY
Endpoints

Every route.

Auth

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
Endpoints

Supported routes

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.
Compatibility

Cross-compatible client formats

FreeTheAi supports multiple API formats for easier client compatibility. You can use OpenAI-compatible Chat Completions, Anthropic-compatible Messages, and Responses-style routes with the same API key and the same model aliases.

POST /v1/chat/completionsOpenAI-compatible chat completions. Streaming, tool calling, and structured outputs.
POST /v1/messagesAnthropic-compatible Messages route. System prompts, tool use, and the same content blocks Claude clients expect.
POST /v1/responsesResponses-style route. Same key, same model alias.
POST /v1/images/generationsOpenAI-compatible image generation for supported image aliases.
POST /v1/images/editsOpenAI-compatible multipart image edits for supported image aliases.
GET /v1/images/generations/{request_id}Poll async EVE image jobs submitted with background or async enabled.
GET /v1/modelsAuthenticated client catalog.
GET /v1/models/fullCatalog with context, output, capability, and access metadata.
POST /v1/audio/speechText-to-speech route for supported voice aliases.
POST /v1/audio/transcriptionsSpeech-to-text route for OpenAI-style multipart audio uploads.

Pick the route that matches your client. The model alias and the key never change between formats.

Chat Completions

OpenAI-compatible chat

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

curl

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 SDK

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);
Messages API

Anthropic-style clients

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

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." }
    ]
  }'
Model Catalog

List 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.

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

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.