API Documentation

Learn how to integrate aliapi.me API into your applications

Quick Start

Get started with aliapi.me API in minutes. Our API is fully compatible with OpenAI's interface.

1. Get Your API Key

2. Install SDK

Install the OpenAI SDK or use our compatible endpoints.

bash

pip install openai

3. Make Your First Request

Start making requests with your preferred model.

Authentication

All API requests require authentication using your API key.

API Key Header

Include your API key in the Authorization header:

http

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure and never expose them in client-side code.

Chat Completions

Generate conversational responses using various AI models.

Endpoint

http

POST https://api.aliapi.me/v1/chat/completions

Request Parameters

modelID of the model to use

messagesArray of message objects

temperatureSampling temperature (0-2)

max_tokensMaximum tokens to generate

streamEnable streaming responses

Example Request

typescript

import OpenAI from 'openai';

// OpenAI 风格 Base URL
const client = new OpenAI({
  baseURL: 'https://api.aliapi.me/v1',
  apiKey: process.env.API_KEY,
});

// OpenRouter 风格也同样支持:
// baseURL: 'https://api.aliapi.me/api/v1'

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
});

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

Python Example Request

python

from openai import OpenAI

# OpenAI 风格 Base URL
client = OpenAI(
    base_url="https://api.aliapi.me/v1",
    api_key="YOUR_API_KEY"
)

# OpenRouter 风格也同样支持:
# base_url="https://api.aliapi.me/api/v1"

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

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

Available Models

Access hundreds of AI models through a single API.

List Models Endpoint

http

GET https://api.aliapi.me/v1/models

Flagship Models

Latest and most capable models from major providers

Coding Specialist

Optimized for code generation and technical tasks

Reasoning Models

Advanced reasoning and complex problem-solving

Multimodal

Support for images, audio, and video inputs

Streaming Responses

Stream responses in real-time for better user experience.

Benefits of streaming:

Reduced perceived latency
Real-time feedback
Better UX for long responses

Implementation Example

typescript

const stream = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Image Generation

Generate images from a text prompt with an OpenAI-compatible endpoint. Works with the official OpenAI SDKs — just point base_url at our API.

Endpoints

http

POST https://api.aliapi.me/v1/images/generations
POST https://api.aliapi.me/v1/images/edits

Request parameters

modelRequired. An image model ID, e.g. earth/grok-imagine-image-quality or earth/gpt-image-2.
promptRequired. Text description of the image you want.
nOptional. Number of images to generate. Defaults to 1. Some upstreams only support 1.
sizeOptional. Output size such as 1024x1024. Support depends on the model; ignored when the upstream does not accept it.
image_sizeOptional. Resolution tier: 1K, 2K or 4K (aliases 1024/2048/4096, case-insensitive). Gemini image models only. Any other value returns 400.
response_formatOptional. url (default) or b64_json. Use b64_json when you want the bytes inline instead of a link.

Aspect ratio & resolution

size controls the aspect ratio. image_size controls the resolution tier and is currently supported by Gemini image models only.

Accepted aspect ratios

Pass a ratio directly — 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 21:9, 5:4, 4:5. OpenAI-style pixel sizes are mapped for you: 1024x1024→1:1, 1792x1024→16:9, 1024x1792→9:16, 1536x1024→3:2, 1024x1536→2:3.

Resolution tiers (image_size)

1K, 2K or 4K. Measured on gemini-3.1-flash-image-preview at 16:9 — 1K = 1376x768, 2K = 2752x1536, 4K = 5504x3072. Billing follows the actual output tokens, so 4K costs roughly twice a 1K image.

gemini_aspect_ratio and gemini_image_size are accepted as aliases of size and image_size. An explicit image_size outside 1K/2K/4K returns 400 instead of being silently ignored. These parameters apply to /v1/images/generations only — /v1/images/edits does not support them.

Example: 4K, 16:9

bash

curl https://api.aliapi.me/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "earth/gemini-3.1-flash-image-preview",
    "prompt": "A serene mountain landscape at sunset",
    "n": 1,
    "size": "16:9",
    "image_size": "4K"
  }'

# → 5504x3072

Example

bash

curl https://api.aliapi.me/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "earth/grok-imagine-image-quality",
    "prompt": "A red apple on a white table, product photo",
    "n": 1
  }'

# → {"created": 1786000000,
#    "data": [{"url": "https://.../image.jpeg"}]}

Python Example

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.aliapi.me/v1",
)

result = client.images.generate(
    model="earth/grok-imagine-image-quality",
    prompt="A red apple on a white table, product photo",
    n=1,
)
print(result.data[0].url)

Image models do not work on /v1/chat/completions

Sending an image model to the chat endpoint returns 400 Model not found — the request is forwarded upstream and rejected there. Always use /v1/images/generations.

bash

# ❌ Wrong: image model on the chat endpoint
curl https://api.aliapi.me/v1/chat/completions \
  -d '{"model": "earth/grok-imagine-image-quality", "messages": [...]}'
# → 400 {"error": {"message": "Model not found: ..."}}

# ✅ Correct: use the images endpoint
curl https://api.aliapi.me/v1/images/generations \
  -d '{"model": "earth/grok-imagine-image-quality", "prompt": "..."}'

Billing modes

Image models bill in one of two ways. Check the Pricing tab on any model page to see which one applies.

per_imageFlat fee per generated image, independent of prompt length — e.g. $0.05 per image for earth/grok-imagine-image-quality, $0.19 for the earth/gpt-image-2 family.
image_tokenBilled by tokens (per 1M): output image tokens, plus input tokens on models that accept image input (e.g. edits). Used by the Gemini, GPT-5 image and GPT Image 2 (4K-token) models. Larger or higher-detail images cost more.

Notes

Returned URLs point at the upstream provider and are temporary — download and store the image on your own storage right away.
Use /v1/images/edits to edit an existing image; send the source image as multipart/form-data.
Generation typically takes a few seconds; keep your client timeout at 120s or higher for large sizes.
Some Gemini image models return the image inside a chat response instead — see the Quickstart tab on the model page for the exact call.

Video Generation

Generate videos from text prompts or reference images. Video models support two calling styles: a synchronous convenience endpoint that blocks until the video is ready, and an asynchronous submit + poll flow.

Synchronous call

The request blocks until generation finishes and returns the video URL directly. Generation usually takes 1–4 minutes — set your client timeout to at least 600 seconds.

http

POST https://api.aliapi.me/v1/videos/generations

bash

curl https://api.aliapi.me/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "earth/seedance-2.0",
    "prompt": "A calico cat stretching on a sunny windowsill, cinematic close-up",
    "duration": 4,
    "resolution": "720p"
  }'

# → {"created": 1753776000, "data": [{"url": "https://...mp4"}]}

Asynchronous call (submit + poll)

Submit a job and get a job object back immediately, then poll the job until it reaches a terminal status. Recommended for production workloads — no long-lived connection required.

http

POST https://api.aliapi.me/v1/videos
GET  https://api.aliapi.me/v1/videos/{id}

1. Submit a job

bash

curl https://api.aliapi.me/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "earth/seedance-2.0",
    "prompt": "A calico cat stretching on a sunny windowsill, cinematic close-up",
    "duration": 4,
    "resolution": "720p"
  }'

# → {"id": "<job_id>", "object": "video.generation",
#    "model": "earth/seedance-2.0", "status": "queued", "created_at": 1753776000}

2. Poll for the result

Poll every 5–10 seconds until the status is completed or failed.

bash

curl https://api.aliapi.me/v1/videos/<job_id> \
  -H "Authorization: Bearer YOUR_API_KEY"

# in_progress → {"status": "in_progress", ...}
# completed   → {"status": "completed", "url": "https://...mp4", "seconds": 4}
# failed      → {"status": "failed", "error": {"code": "...", "message": "..."}}

Full Python example

python

import requests, time

API = "https://api.aliapi.me"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. Submit / 提交任务
job = requests.post(f"{API}/v1/videos", headers=headers, json={
    "model": "earth/seedance-2.0",
    "prompt": "A calico cat stretching on a sunny windowsill, cinematic close-up",
    "duration": 4,
    "resolution": "720p",
}, timeout=30).json()

# 2. Poll until terminal status / 轮询直到终态
while job["status"] in ("queued", "in_progress"):
    time.sleep(5)
    job = requests.get(f"{API}/v1/videos/{job['id']}", headers=headers, timeout=30).json()

if job["status"] == "completed":
    print(job["url"])  # MP4 URL, valid 24h / 有效期 24 小时
else:
    print("failed:", job.get("error"))

Job status

queuedThe job has been accepted and is waiting to start.
in_progressThe video is being generated.
completedDone — the response contains the video url (MP4) and seconds (duration).
failedGeneration failed — the response contains an error object with code and message.

Notes

Idempotency: send an Idempotency-Key header (or external_task_id in the body); retrying with the same key returns the existing job instead of creating a duplicate.
Concurrency: up to 20 in-flight jobs per user — wait for jobs to finish before submitting more.
Add "wait": true to the POST /v1/videos body to make it block until the job finishes (equivalent to the synchronous endpoint).
The returned video URL is valid for 24 hours — download and store it promptly.

Anthropic Native API

aliapi.me fully supports Anthropic's native /v1/messages API format. You can use the official Anthropic SDK directly, with support for streaming and Prompt Cache.

Base URL

Set the Anthropic SDK's base_url to the following address, using your aliapi.me API Key:

http

Base URL: https://api.aliapi.me

Python SDK

python

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.aliapi.me",
    api_key="YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(message.content[0].text)

TypeScript SDK

typescript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.aliapi.me',
  apiKey: 'YOUR_API_KEY',
});

const message = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude!' }
  ],
});

console.log(message.content[0].text);

Streaming

Use the Anthropic SDK's stream method for streaming output:

python

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Prompt Cache

Enable prompt caching with the cache_control parameter to reduce repeated token costs:

python

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "You are a helpful assistant...(long system prompt)...",
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

# Check cache usage
print(f"Cache read: {message.usage.cache_read_input_tokens}")
print(f"Cache creation: {message.usage.cache_creation_input_tokens}")

cURL Example

Call the API directly using HTTP:

bash

curl https://api.aliapi.me/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Supported Models

The following Claude models are currently available via the native API format:

Claude Opus 4

claude-opus-4-6

Claude Sonnet 4

claude-sonnet-4-6

Claude Haiku 3.5

claude-haiku-4-5

Error Handling

Understand and handle API errors effectively.

Common Error Codes

401401 Unauthorized - Invalid API key
429429 Too Many Requests - Rate limit exceeded
500500 Internal Server Error - Service error
503503 Service Unavailable - Temporary outage

Best Practices

Implement exponential backoff for retries
Handle rate limits gracefully
Log errors for debugging

Pricing & Billing

Transparent pricing based on actual usage.

Model	Input Price	Output Price
GPT-4	$5.00	$15.00
GPT-3.5 Turbo	$0.50	$1.50
Claude 3 Opus	$15.00	$75.00

per 1M tokens

Pay-as-you-go pricing with no subscription required.

Track your usage and costs in real-time from the dashboard.

Billing & Usage API

Query your account's usage and spend programmatically in an OpenAI Usage/Costs API compatible format: aggregate by API key × model, with hourly/daily time buckets, plus configurable spend alerts. Built for reconciliation scripts, cost dashboards, and automated monitoring.

Admin Key required

All endpoints in this section require an Admin Key. Tick "Admin Key" when creating a key in Settings → API Keys (you can also toggle it later). Calls with a standard inference key return 403.

Admin Keys are management-only: they can query usage/costs, manage alert rules, and check credits (/v1/credits, /v1/auth/key), but cannot call model inference — use a standard key for that. Admin Keys keep working even when your balance is zero.

Endpoints

http

GET  https://api.aliapi.me/v1/organization/usage/completions
GET  https://api.aliapi.me/v1/organization/costs
GET  https://api.aliapi.me/v1/organization/alerts
POST https://api.aliapi.me/v1/organization/alerts
PUT  https://api.aliapi.me/v1/organization/alerts/{id}
DELETE https://api.aliapi.me/v1/organization/alerts/{id}

# Read-only self queries (both Admin and standard keys)
GET  https://api.aliapi.me/v1/credits
GET  https://api.aliapi.me/v1/auth/key

Query parameters (shared by usage & costs)

start_timeRequired. Start of the range, Unix seconds.
end_timeOptional. End of the range, Unix seconds. Defaults to now.
bucket_widthBucket granularity: 1h or 1d (default 1d). Bucket boundaries align to your account timezone (default UTC+8, changeable in Settings → Account).
group_byGroup dimensions: api_key_id and/or model. Ungrouped dimensions are null in results.
api_key_ids / modelsFilter by API key IDs / model IDs. Only keys belonging to your account match.
limit / pagelimit = number of buckets (1h: default 24, max 720; 1d: default 7, max 180); page = cursor from the previous response.

Query token usage

bash

curl "https://api.aliapi.me/v1/organization/usage/completions?start_time=1787328000&bucket_width=1d&group_by=api_key_id&group_by=model" \
  -H "Authorization: Bearer $ADMIN_KEY"

json

{
  "object": "page",
  "data": [
    {
      "object": "bucket",
      "start_time": 1787328000,
      "end_time": 1787414400,
      "results": [
        {
          "object": "organization.usage.completions.result",
          "input_tokens": 15234,
          "output_tokens": 8721,
          "input_cached_tokens": 4096,
          "num_model_requests": 37,
          "api_key_id": "key_xxx",
          "model": "gpt-4o-mini"
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

Query spend

costs returns USD amounts actually charged (after discounts). Consumption refunds appear as separate line_item="adjustment" rows with negative amounts, so the API always reconciles with what you were billed.

json

{
  "object": "bucket",
  "start_time": 1787328000,
  "end_time": 1787414400,
  "results": [
    {
      "object": "organization.costs.result",
      "amount": { "value": 12.3456, "currency": "usd" },
      "line_item": null,
      "api_key_id": "key_xxx",
      "model": "gpt-4o-mini"
    },
    {
      "object": "organization.costs.result",
      "amount": { "value": -2.0, "currency": "usd" },
      "line_item": "adjustment",
      "api_key_id": null,
      "model": null
    }
  ]
}

Reconciliation: treat costs as the source of truth. Multiplying usage tokens by list prices will drift due to cached-token pricing, tiered rates, and discounts.

Sum of rows with line_item=null = total consumption (matches total_usage in /v1/credits); sum including adjustment rows = net spend (matches your balance ledger).

Spend alerts

Set a USD threshold on an hourly (1h) or calendar-day (1d) window. When spend in the window reaches the threshold, you get an in-app notification (including current balance) — at most once per window. Rules are evaluated every 5 minutes.

bash

curl -X POST "https://api.aliapi.me/v1/organization/alerts" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"windowKind": "1h", "threshold": 5.0, "enabled": true}'

Current channel: in-app notifications (rules can also be managed in Settings → Usage Alerts). Email notifications are not yet available.

Limits & notes

•Timezone: buckets and alert windows are cut in your account timezone (default UTC+8); start_time/end_time in requests and responses are always Unix seconds, timezone-independent.
•Freshness: data is queryable within 5 minutes of request completion (typically seconds).
•Rate limit: 30 requests/minute per key on these endpoints; 429 beyond that.
•Range caps: up to 90 days for 1h buckets, 365 days for 1d; max 5000 results per page (buckets × group combinations) — narrow the range or drop a group_by if exceeded.

SDKs & Libraries

Official and community-maintained SDKs for popular languages.

Official SDKs

Python

Use the official OpenAI Python library

pip install openai

Node.js / TypeScript

Use the official OpenAI Node.js library

npm install openai

Popular Frameworks

•

LangChain: LangChain integration for building AI applications

•

Vercel AI SDK: Vercel AI SDK for React and Next.js applications

Rate Limits

API usage limits to ensure fair access and service stability.

Tier	Requests	Tokens
Free	100 req/day	100K tokens/day
Pro	10,000 req/day	10M tokens/day

Rate limit information is included in response headers:

http

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1640995200

Support & Resources

Community

Join our Discord community for help and discussions

Email Support

Contact our team at support@openllm.dev

Status Page

Check real-time API status and uptime

Changelog

Stay updated with latest features and improvements