API reference

Clients

freetheai.FreeTheAI

Bases: _Base

Client for the FreeTheAI API.

from freetheai import FreeTheAI

client = FreeTheAI()  # reads FREETHEAI_API_KEY
reply = client.chat.completions.create(
    model="fta/zai/glm-5.3",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(reply["choices"][0]["message"]["content"])

fallback_models are tried in order when a model is busy, filtered, over its provider budget, or down. max_concurrency caps replies in flight; without it the client learns the account's limit by itself. stream_transport (on by default) fetches non-streamed chats as a stream and assembles them, which keeps long replies from timing out.

search(query, *, num_results=None)

Searches the web; returns results with title, url, and text.

answer(query, *, num_results=None)

Answers a question from the web; returns answer and sources.

close()

freetheai.AsyncFreeTheAI

Bases: _Base

Async client for the FreeTheAI API (same options and methods, awaited).

search(query, *, num_results=None) async

answer(query, *, num_results=None) async

close() async

Resources

Attribute	Methods
client.chat.completions	create(model, messages, stream=False, fallback_models=None, **params), stream_text(model, messages, **params)
client.models	list()
client.videos	create(model, prompt=None, **params)
client.images	generate(model, prompt, **params)
client.tasks	list(limit=None), get(task_id), wait(task_id, poll_interval=5, timeout=1800), content(task_id, index=0)

The async client has the same resources with awaitable methods.

Errors

Errors raised by the client, and how each API answer maps onto them.

The API's error bodies are stable, so the client recognises the common cases (daily check-in, daily limit, a busy model, a content filter, ...) and raises a specific class you can catch, with the error id to quote when you ask for support.

FreeTheAIError

Bases: Exception

Base class for every error this package raises.

APIConnectionError

Bases: FreeTheAIError

The request never got an answer (network error or timeout).

StreamInterruptedError

Bases: FreeTheAIError

A streamed reply stopped before the model said it was finished.

partial holds the text that arrived before the cut.

TaskFailedError

Bases: FreeTheAIError

An image or video task ended without output.

APIStatusError

Bases: FreeTheAIError

The API answered with an error status.

BadRequestError

Bases: APIStatusError

400: the request was invalid.

ContentFilterError

Bases: BadRequestError

400: the model's content filter refused the request or its reply. Rephrasing or another model usually works.

ImagesNotSupportedError

Bases: BadRequestError

400: the model reads text only; remove images or pick another model.

RequestTooLargeError

Bases: APIStatusError

413: the request body is over the size limit (shorten the chat or drop images).

AuthenticationError

Bases: APIStatusError

401: the API key is missing, wrong, or revoked.

IncompleteKeyError

Bases: AuthenticationError

The key is only part of a key (a copied prefix, or cut off). Keys are shown once; create a new one if you lost it.

PermissionDeniedError

Bases: APIStatusError

403: this key may not do this.

CheckinRequiredError

Bases: PermissionDeniedError

403: free models need the daily check-in on the website first.

EmailNotVerifiedError

Bases: PermissionDeniedError

403: confirm the account's email address before using the API.

NotFoundError

Bases: APIStatusError

404: unknown task or route.

ModelNotFoundError

Bases: NotFoundError

404: no model has this ID. suggestions lists close model IDs.

RateLimitError

Bases: APIStatusError

429: too many requests.

ConcurrencyLimitError

Bases: RateLimitError

429: the account already has as many replies running as its plan allows.

DailyLimitError

Bases: RateLimitError

429: today's free requests are used up; resets_at is 00:00 UTC.

ProviderBudgetError

Bases: RateLimitError

429: today's token budget for this model's provider is used up. Models from other providers still work.

InternalServerError

Bases: APIStatusError

5xx: the service or model is temporarily unavailable.

ModelBusyError

Bases: InternalServerError

503: every route for this model is busy; retry later or use another model.