Free AI API

https://freetheai.xyz
Admin
An OpenAI-compatible API gateway providing access to 16,000+ AI models including chat, streaming,...
Tokens:5,138
Snippets:46
Trust Score:4.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### cURL List Models

Source: https://freetheai.xyz/docs

Example using cURL to retrieve a list of supported models. This endpoint is for normal clients.

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

--------------------------------

### Base API Setup

Source: https://freetheai.xyz/docs

Configure your API client with the base URL and authentication method. Use your API key as a bearer token.

```text
Base URL: https://api.freetheai.xyz/v1
Auth:     Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Get a Key

Source: https://freetheai.xyz/docs

Obtain an API key by joining Discord and using the /signup command. The same key is used for all API services. If lost, use /resetkey.

```APIDOC
## Get a key
Join Discord and run `/signup`. Send the key as a bearer token. If you lose it, run `/resetkey`.
```
Base URL: https://api.freetheai.xyz/v1
Auth:     Authorization: Bearer YOUR_API_KEY
```
```

--------------------------------

### JavaScript SDK Chat Completions

Source: https://freetheai.xyz/docs

Example using the OpenAI JavaScript SDK to interact with the chat completions endpoint. Configure the SDK with your API key and the custom base URL.

```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: "glm/glm-5.1",
  messages: [{ role: "user", content: "Reply with OK." }]
});

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

--------------------------------

### cURL List Full Model Catalog

Source: https://freetheai.xyz/docs

Example using cURL to retrieve the full model catalog, including tier and catalog metadata. Useful for UI implementations.

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

--------------------------------

### cURL Image Edit

Source: https://freetheai.xyz/docs

Example using cURL to edit an image. Requires the 'img/gpt-image-2' model and a base64 encoded input image.

```bash
curl https://api.freetheai.xyz/v1/images/edits \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "img/gpt-image-2",
    "prompt": "Improve this logo and make it cleaner",
    "image": "data:image/png;base64,BASE64_IMAGE_HERE"
  }'
```

--------------------------------

### JavaScript OpenAI Client for Chat Completions

Source: https://freetheai.xyz/

Initialize the OpenAI client with your API key and base URL to interact with the chat completions endpoint. This example demonstrates how to create a chat completion with streaming enabled.

```javascript
import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "glm/glm-5.1",
  messages: [{ role: "user", content: "Ship a tiny REST API example." }],
  stream: true
});
```

--------------------------------

### cURL Image Generation

Source: https://freetheai.xyz/docs

Example using cURL to generate an image. Specify the model and prompt. The response may contain base64 data or a URL.

```bash
curl https://api.freetheai.xyz/v1/images/generations \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vhr/gpt_image_2",
    "prompt": "A cinematic neon sports car parked under rainy city lights"
  }'
```

--------------------------------

### cURL Chat Completions

Source: https://freetheai.xyz/docs

Example using cURL to send a chat completion request. Supports streaming and tool calling. Ensure your API key is set as an environment variable.

```bash
curl https://api.freetheai.xyz/v1/chat/completions \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm/glm-5.1",
    "messages": [
      { "role": "user", "content": "Write a tiny Flask route." }
    ],
    "stream": true
  }'
```

--------------------------------

### cURL Messages API

Source: https://freetheai.xyz/docs

Example using cURL to send a request to the Anthropic-style Messages API. Specify the model, max tokens, and messages.

```bash
curl https://api.freetheai.xyz/v1/messages \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rev/claude-sonnet-4.5",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "Give me a short implementation plan." }
    ]
  }'
```

--------------------------------

### List Models

Source: https://freetheai.xyz/docs

Retrieve a list of supported models. Use `/v1/models` for standard client access and `/v1/models/full` to include tier and catalog metadata for UI purposes.

```APIDOC
## List models
Use `/v1/models` for normal clients. Use `/v1/models/full` when you need tier and catalog metadata for a UI. 
### Client catalog
```
curl https://api.freetheai.xyz/v1/models \
  -H "Authorization: Bearer $FREETHEAI_API_KEY"
```

### Full catalog
```
curl "https://api.freetheai.xyz/v1/models/full" \
  -H "Authorization: Bearer $FREETHEAI_API_KEY"
```
```

--------------------------------

### Chat Completions

Source: https://freetheai.xyz/docs

Use this endpoint for OpenAI-compatible chat, streaming, tool calling, and multi-turn conversations. Point your clients to the base URL and use model aliases from the /models endpoint.

```APIDOC
## OpenAI-compatible chat
Point OpenAI-compatible clients at `https://api.freetheai.xyz/v1`. Use exact model aliases from /models. 
### curl
```
curl https://api.freetheai.xyz/v1/chat/completions \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "model": "glm/glm-5.1", \
    "messages": [ \
      { "role": "user", "content": "Write a tiny Flask route." } \
    ], \
    "stream": true \
  }'
```

### JavaScript SDK
```
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: "glm/glm-5.1",
  messages: [{ role: "user", content: "Reply with OK." }]
});

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

--------------------------------

### Generate and Save Image with Python

Source: https://freetheai.xyz/docs

Use this helper function to generate an image using the FreeTheAI API and save it to a specified path. It handles both base64 encoded images and direct URLs. Ensure your API key is set as an environment variable 'FREETHEAI_API_KEY'.

```python
import base64
import os
from pathlib import Path

import requests

API_KEY = os.environ["FREETHEAI_API_KEY"]
API_BASE = "https://api.freetheai.xyz/v1"


def save_image_result(result, output_path):
    item = (result.get("data") or [{}])[0]
    if item.get("b64_json"):
        Path(output_path).write_bytes(base64.b64decode(item["b64_json"]))
        return
    if item.get("url"):
        image = requests.get(item["url"], timeout=120)
        image.raise_for_status()
        Path(output_path).write_bytes(image.content)
        return
    raise RuntimeError(f"No image found in response: {result}")


res = requests.post(
    f"{API_BASE}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "vhr/gpt_image_2",
        "prompt": "A clean product mockup on a dark desk",
    },
    timeout=180,
)
res.raise_for_status()
save_image_result(res.json(), "generated.png")
```

--------------------------------

### Chat Completions

Source: https://freetheai.xyz/

Standard chat completions for apps, CLIs, and agents. This endpoint is compatible with OpenAI's chat completions API.

```APIDOC
## POST /v1/chat/completions

### Description
Provides chat completions using various models.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for chat completions.
- **messages** (array) - Required - An array of message objects representing the conversation.
  - **role** (string) - Required - The role of the message sender (e.g., "user", "system", "assistant").
  - **content** (string) - Required - The content of the message.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
```json
{
  "model": "glm/glm-5.1",
  "messages": [
    {
      "role": "user",
      "content": "Build me a clean product launch checklist"
    }
  ],
  "stream": true
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of completion choices.
  - **message** (object) - The message content.
    - **role** (string) - The role of the message sender.
    - **content** (string) - The content of the message.
- **usage** (object) - Information about token usage.
  - **prompt_tokens** (integer) - The number of prompt tokens.
  - **completion_tokens** (integer) - The number of completion tokens.
  - **total_tokens** (integer) - The total number of tokens.

### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Here is a product launch checklist..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60
  }
}
```
```

--------------------------------

### OpenAI-Compatible Chat Completion Request

Source: https://freetheai.xyz/

Use this cURL command to make a chat completion request to the API. Ensure your API key is set as an environment variable. Supports streaming responses.

```curl
curl https://api.freetheai.xyz/v1/chat/completions \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm/glm-5.1",
    "messages": [
      {
        "role": "user",
        "content": "Build me a clean product launch checklist"
      }
    ],
    "stream": true
  }'
```

--------------------------------

### Image Generation Request

Source: https://freetheai.xyz/

Generate an image using the specified model by sending a POST request to the images/generations endpoint. Include your prompt and desired model.

```curl
curl https://api.freetheai.xyz/v1/images/generations \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vhr/gpt_image_2",
    "prompt": "A minimal flat logo for a dev tool"
  }'
```

--------------------------------

### Image Generation

Source: https://freetheai.xyz/

Generate images using specified models. This endpoint supports image generation based on text prompts.

```APIDOC
## POST /v1/images/generations

### Description
Generates images based on a text prompt using various models.

### Method
POST

### Endpoint
/v1/images/generations

### Parameters
#### Request Body
- **model** (string) - Required - The image generation model to use (e.g., "vhr/gpt_image_2").
- **prompt** (string) - Required - A text description of the desired image.

### Request Example
```json
{
  "model": "vhr/gpt_image_2",
  "prompt": "A minimal flat logo for a dev tool"
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of generated image objects.
  - **url** (string) - The URL of the generated image.

### Response Example
```json
{
  "data": [
    {
      "url": "https://api.freetheai.xyz/images/generated/image1.png"
    }
  ]
}
```
```

--------------------------------

### Image Edit

Source: https://freetheai.xyz/docs

Edit existing images using the `img/gpt-image-2` model. Requires a base64 data URL of the input image.

```APIDOC
### Image edit
```
curl https://api.freetheai.xyz/v1/images/edits \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "model": "img/gpt-image-2", \
    "prompt": "Improve this logo and make it cleaner", \
    "image": "data:image/png;base64,BASE64_IMAGE_HERE" \
  }'
```
```

--------------------------------

### Image Generation

Source: https://freetheai.xyz/docs

Generate images using specified models. The response may contain either `b64_json` or a `url`.

```APIDOC
### Image generation
```
curl https://api.freetheai.xyz/v1/images/generations \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "model": "vhr/gpt_image_2", \
    "prompt": "A cinematic neon sports car parked under rainy city lights" \
  }'
```
```

--------------------------------

### Python Image Editing with Base64 Input

Source: https://freetheai.xyz/

Edit an image using the images/edits endpoint in Python. This function takes a prompt and an image file path, encodes the image to base64, and sends it with the request.

```python
import base64, requests, os

def edit_image(prompt, image_path):
    with open(image_path, "rb") as f:
        data_url = "data:image/png;base64," + \
            base64.b64encode(f.read()).decode()

    return requests.post(
        "https://api.freetheai.xyz/v1/images/edits",
        headers={
            "Authorization": f"Bearer {os.environ['FREETHEAI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "img/gpt-image-2",
            "prompt": prompt,
            "image": data_url,
        },
    ).json()
```

--------------------------------

### Image Editing

Source: https://freetheai.xyz/

Edit existing images using a prompt and base64 encoded image data. This endpoint allows for modifications to images based on textual instructions.

```APIDOC
## POST /v1/images/edits

### Description
Edits an existing image based on a prompt and provided image data.

### Method
POST

### Endpoint
/v1/images/edits

### Parameters
#### Request Body
- **model** (string) - Required - The image editing model to use (e.g., "img/gpt-image-2").
- **prompt** (string) - Required - A text description of the desired edits.
- **image** (string) - Required - The base64 encoded image data.

### Request Example
```json
{
  "model": "img/gpt-image-2",
  "prompt": "Add a subtle glow effect",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of edited image objects.
  - **url** (string) - The URL of the edited image.

### Response Example
```json
{
  "data": [
    {
      "url": "https://api.freetheai.xyz/images/edited/image1_edited.png"
    }
  ]
}
```
```

--------------------------------

### Messages API

Source: https://freetheai.xyz/

Anthropic-style messages route for compatible frameworks. This endpoint allows for message-based interactions similar to Anthropic's API.

```APIDOC
## POST /v1/messages

### Description
Handles message-based API requests in an Anthropic-compatible format.

### Method
POST

### Endpoint
/v1/messages

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generating the response.
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **messages** (array) - Required - An array of message objects representing the conversation.
  - **role** (string) - Required - The role of the message sender (e.g., "user", "assistant").
  - **content** (string) - Required - The content of the message.

### Request Example
```json
{
  "model": "rev/claude-sonnet-4.5",
  "max_tokens": 256,
  "messages": [
    { "role": "user", "content": "Reply with a compact migration plan." }
  ]
}
```

### Response
#### Success Response (200)
- **content** (array) - The content of the response message.
  - **type** (string) - The type of content (e.g., "text").
  - **text** (string) - The text content of the response.
- **usage** (object) - Information about token usage.
  - **input_tokens** (integer) - The number of input tokens.
  - **output_tokens** (integer) - The number of output tokens.

### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "Migration Plan: Phase 1: Assessment..."
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 100
  }
}
```
```

--------------------------------

### Anthropic-Style Messages API Request

Source: https://freetheai.xyz/

Make a request to the messages endpoint using cURL, mimicking Anthropic's API structure. This is useful for frameworks compatible with Anthropic's message format.

```curl
curl https://api.freetheai.xyz/v1/messages \
  -H "Authorization: Bearer $FREETHEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rev/claude-sonnet-4.5",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "Reply with a compact migration plan." }
    ]
  }'
```
Tokens:
Raw