ClearAI

API Documentation

Quick Start

Get started with ClearAI API in under a minute.

ClearAI provides API access to powerful AI models. You can use it as a drop-in replacement for OpenAI or Anthropic by simply changing the base URL and API key.

Base URL: https://api.clearai.cc

1. Get an API Key

Create an API key in the Settings → API section of the chat interface. Your key will look like clear_<random_hex>.

2. Make Your First Request

bash

curl https://api.clearai.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer clear_YOUR_API_KEY" \
  -d '{
    "model": "clear-talking",
    "messages": [
      {"role": "user", "content": "Hello! Who are you?"}
    ]
  }'

3. Quick Test

Replace clear_YOUR_API_KEY with your actual key and run the curl command above. You'll get a JSON response with the AI's reply.

Authentication

All API requests require authentication via API key.

Keep your API keys secret. Never share them or commit them to version control.

Method 1: Bearer Token (OpenAI-compatible)

Pass the API key via the Authorization: Bearer header.

text

Authorization: Bearer clear_YOUR_API_KEY

Method 2: x-api-key Header (Anthropic-compatible)

Pass the API key via the x-api-key header for Anthropic-compatible endpoints.

text

x-api-key: clear_YOUR_API_KEY

API Key Format

text

clear_<random_hex_string>

Models

Available models and their use cases.

ClearAI offers five models optimized for different tasks. Choose the one that best fits your use case.

Model ID	Use Case	Description	Max Tokens
clear-talking	Conversation	General-purpose chat, quick answers, everyday Q&A	1,000
clear-coding	Programming	Code generation, debugging, technical tasks	2,000
clear-thinking	Analysis	Complex reasoning, deep analysis, problem-solving	4,000
clear-researching	Research	Structured research, data analysis, reports	2,000
clear-funny	Fun	Humorous responses, jokes, fun conversations	1,000

Tip: Use clear-coding for programming and clear-thinking for complex analytical tasks.

OpenAI-compatible API

Use any OpenAI SDK or library by changing the base URL and API key.

Endpoint

text

POST https://api.clearai.cc/v1/chat/completions

Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID: clear-talking, clear-coding, clear-thinking, clear-researching, clear-funny
messages	array	Yes	Array of {role, content} objects
temperature	number	No	Sampling temperature (0-1). Default: 0.3
max_tokens	number	No	Maximum tokens in response. Default: varies by model
stream	boolean	No	Enable SSE streaming. Default: false

cURL Example

bash

curl https://api.clearai.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer clear_YOUR_API_KEY" \
  -d '{
    "model": "clear-coding",
    "messages": [
      {"role": "user", "content": "Write a Node.js HTTP server"}
    ],
    "temperature": 0.2,
    "max_tokens": 2000
  }'

JavaScript (fetch)

javascript

const response = await fetch("https://api.clearai.cc/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer clear_YOUR_API_KEY"
  },
  body: JSON.stringify({
    model: "clear-coding",
    messages: [
      { role: "user", content: "Write a Node.js HTTP server" }
    ],
    temperature: 0.2
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

Python (openai SDK)

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.clearai.cc/v1",
    api_key="clear_YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="clear-coding",
    messages=[
        {"role": "user", "content": "Write a Node.js HTTP server"}
    ],
    temperature=0.2
)

print(response.choices[0].message.content)

Response Format

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "clear-coding",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Here's a Node.js HTTP server..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 35,
    "completion_tokens": 150,
    "total_tokens": 185
  }
}

Streaming (SSE)

Set stream: true to receive server-sent events with data: {...} chunks and a final data: [DONE] message.

javascript

const response = await fetch("https://api.clearai.cc/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer clear_YOUR_API_KEY"
  },
  body: JSON.stringify({
    model: "clear-talking",
    messages: [{ role: "user", content: "Count to 5" }],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  const lines = text.split("\\n").filter(l => l.startsWith("data: "));

  for (const line of lines) {
    const data = line.slice(6);
    if (data === "[DONE]") break;
    const parsed = JSON.parse(data);
    const content = parsed.choices?.[0]?.delta?.content || "";
    process.stdout.write(content);
  }
}

Anthropic-compatible API

Connect Claude Code and other Anthropic SDK clients.

Endpoint

text

POST https://api.clearai.cc/anthropic/v1/messages

Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID: clear-talking, clear-coding, clear-thinking, clear-researching, clear-funny
messages	array	Yes	Array of {role, content} objects
system	string	No	System prompt for the AI
max_tokens	number	No	Maximum tokens in response
temperature	number	No	Sampling temperature (0-1)
stream	boolean	No	Enable SSE streaming. Default: false

cURL Example

bash

curl https://api.clearai.cc/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: clear_YOUR_API_KEY" \
  -d '{
    "model": "clear-coding",
    "system": "You are a helpful coding assistant.",
    "messages": [
      {"role": "user", "content": "Write a Fibonacci function in Python"}
    ],
    "max_tokens": 2000
  }'

Response Format

json

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "clear-coding",
  "content": [{
    "type": "text",
    "text": "Here's a Fibonacci function in Python..."
  }],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 35,
    "output_tokens": 120
  }
}

Streaming (Anthropic SSE format)

Set stream: true to receive Anthropic-style SSE events (message_start, content_block_delta, message_stop).

Claude Code Integration

Connect ClearAI as your AI provider in Claude Code.

ClearAI supports the Anthropic API format, which means it works seamlessly with Claude Code (Claude's CLI tool). Just configure your Claude Code CLI to use ClearAI as the API backend.

1. Create a CLAUDE.md File

Create a CLAUDE.md file in your project root with this configuration:

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.clearai.cc/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "clear_YOUR_API_KEY",
    "ANTHROPIC_MODEL": "clear-coding",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "clear-talking"
  },
  "model": "clear-coding"
}

2. Start Claude Code

Run Claude Code in your project directory — it will automatically pick up the settings:

bash

claude

Model Recommendations:

clear-coding — for coding and technical tasks (recommended for Claude Code)
clear-talking — for general conversation and quick answers
clear-thinking — for complex analysis and reasoning tasks
clear-researching — for structured research and reports

Optional: Claude Code Settings

You can also configure Claude Code globally by editing ~/.claude/settings.json:

json

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.clearai.cc/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "clear_YOUR_API_KEY",
    "ANTHROPIC_MODEL": "clear-coding"
  }
}

Using the Anthropic API Directly

You can also use the Anthropic Python SDK or any Anthropic-compatible library:

python

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.clearai.cc/anthropic",
    api_key="clear_YOUR_API_KEY"
)

response = client.messages.create(
    model="clear-coding",
    max_tokens=2000,
    system="You are a helpful coding assistant.",
    messages=[
        {"role": "user", "content": "Write a React component"}
    ]
)

print(response.content[0].text)

Error Codes

Common API errors and their meaning.

The API returns standard HTTP status codes and a JSON error body with a type field for easy handling.

Status	Error Type	Description	Action
401	auth	Invalid or missing API key	Check your API key and auth header
402	insufficient_balance	Not enough tokens	Top up your balance in settings
403	blocked	Account is blocked	Contact support
404	model	Model not found or disabled	Check the model ID
429	rate_limit	Too many requests	Slow down and retry with backoff
429	limit	Daily limit exceeded	Wait for daily reset or upgrade
502	provider	AI provider unavailable	Retry in a few seconds
503	maintenance	Service in maintenance mode	Wait for maintenance to complete

Error body format:
{"error": {"message": "...", "type": "..."}}

Limits & Tokens

How billing, tokens, and rate limits work.

How Tokens Work

Tokens are the unit of measurement for API usage. A token is roughly ~4 characters of English text or ~2 characters of Russian/Cyrillic text. Both input (prompt) and output (response) consume tokens.

Token Consumption

Direction	Cost Factor	Explanation
Input (prompt)	Base rate	Your message + system prompt + conversation history
Output (response)	Higher rate	Output tokens cost more than input tokens
Cached	Reduced rate	Repeated requests may be served from cache at lower cost

Model-Specific Consumption

Different models consume tokens at different rates based on their capabilities:

clear-talking — optimized for short, efficient responses. Lowest token consumption.
clear-coding — generates code, which produces longer outputs. Moderate token consumption.
clear-thinking — performs deep analysis with detailed reasoning. Higher output consumption.
clear-researching — produces structured, comprehensive responses. Higher consumption.

Rate Limits

Limit	Value	Scope
Requests per minute	60	Per user
Daily requests	1,000	Per user
Daily tokens	1,000,000	Per user
Max response tokens	1,000—4,000	Depends on model

You can view your current balance and usage in the Settings → Usage section. Top up tokens from the Billing section.

Need help? Contact support or check the settings page for more details.