API Docs

Chat, models, signup, and check-in - one key, one base URL.

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.

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

Header
Authorization: Bearer YOUR_API_KEY
Endpoints

Supported routes

POST/v1/chat/completionsOpenAI-compatible chat, streaming, tool calling, and multi-turn conversations.
POST/v1/messagesAnthropic-compatible Messages route for Claude-style clients and frameworks.
POST/v1/responsesResponses-style route. Same key, same model alias.
GET/v1/modelsAuthenticated model list for normal clients.
GET/v1/models/fullExpanded model catalog with context, output, image-support, and access metadata.
GET/v1/models/leaderboardSite-key model leaderboard for public catalog and landing-page widgets.
POST/v1/audio/speechText-to-speech for role-gated voice aliases such as xai/grok-tts and mim/*tts*.
POST/v1/audio/transcriptionsSpeech-to-text multipart uploads for role-gated voice aliases such as xai/grok-stt.
GET/v1/healthPublic 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.
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 role-gated 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/fullwhen you need tier and catalog metadata for a UI.

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

Errors and rate limits

Error shape

Most API errors use the OpenAI-style envelope. Thetype 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_keyMissing, 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_requiredKey is valid but the Discord owner has not checked in today. Run /checkin in the FreeTheAi Discord server.
403 model_access_deniedModel is limited to Verified members, earned through active server participation.
403 discord_membership_requiredKey owner left the Discord. Rejoin with the same Discord account that owns the key.
403 user_pausedAccount paused by staff. Staff action required.
403 ip_blacklistedSource IP is banned. No client-side fix; staff action required.
403 client_signature_bannedBanned client signature. Switch to a supported client; staff action may be required.

Request validation

400 invalid_request_errorBad 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_exceededPrompt or request is too large. Reduce context, attachments, message history, or requested output tokens.
400 content_policy_violationBlocked by moderation/safety filters. Change the prompt content.
404 invalid_request_errorCurrently used for deferred video lookup when the request id is unknown.

Rate limits, daily caps, and concurrency

429 rate_limit_errorPer-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_errorAlready running the maximum allowed parallel requests. Wait for one to finish.
429 glm_depletedGLM provider quota is depleted for the current 5-hour window. Retry later.
499 client_canceledClient disconnected while the request was still running. Keep the connection open until the response completes.

Provider and gateway

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

Site-only catalog and stats endpoints

401 invalid_request_errorSite-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-AfterSeconds 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_keyYour API key is missing or wrong.
403 daily_checkin_requiredRun /checkin in Discord.
403 model_access_deniedThis model is for Verified members.
400 invalid_request_errorYour request body, model, or route is wrong.
400 context_length_exceededYour prompt or context is too large.
400 content_policy_violationThe request was blocked by moderation.
429 rate_limit_errorYou hit a rate limit, daily cap, or cooldown.
429 concurrency_limit_errorWait for your active request to finish.
502 provider_errorProvider failed unexpectedly. Retry or try another model.
503 provider_unavailableProvider is temporarily unavailable.
504 provider_timeoutProvider took too long.
500/503 server_errorGateway internal issue. Retry once.