Documentation

企业生产接入 · Production integration

面向生产环境、Agent 与自动化流水线。同一套 OpenAI 兼容接口，无需改业务协议。 服务状态见 /status。

推荐模型（生产默认）

SDK 配置建议

# Python — 生产环境建议
from openai import OpenAI

client = OpenAI(
    api_key="sk-ama-YOUR_KEY",
    base_url="https://api.aimodelapi.ai/v1",
    timeout=180.0,   # Agent / 工具调用场景建议 ≥180s
    max_retries=5,
)

# 流式
stream = client.chat.completions.create(
    model="claude-sonnet-latest",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

错误响应与重试

错误 body 包含 type、code、message、request_id。 限流或临时不可用时，响应可能附带 HTTP 头 Retry-After 与 body 字段 retry_after_sec — 请按提示等待后重试。 联系支持时请附上 request_id。

上线前自检

curl -s https://api.aimodelapi.ai/health

export API_KEY=sk-ama-YOUR_KEY
curl -s https://api.aimodelapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-latest","messages":[{"role":"user","content":"OK"}],"max_tokens":16}'

curl -N https://api.aimodelapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-latest","messages":[{"role":"user","content":"1到3"}],"max_tokens":32,"stream":true}'

企业扩容、专用配额或 SLA 洽谈： sales@aimodelapi.ai · 技术支持： support@aimodelapi.ai

Model parity & what customers need

One sk-ama- key + base URL — same setup as other gateways. No TAVILY, MCP, or extra scripts required for chat, coding, or agent tools that run on the client (terminal, files).

Claude Opus 4.6 via ModelAPI

We route to AWS Bedrock us.anthropic.claude-opus-4-6-v1 — the same inference stack as Bedrock's official Opus 4.6. Reasoning, coding, streaming, and tool calling (Claude Code, Hermes terminal, etc.) are supported.

Default setup (no extra installs)

# Claude Code
export ANTHROPIC_BASE_URL=https://api.aimodelapi.ai   # no /v1
export ANTHROPIC_API_KEY=sk-ama-YOUR_KEY

# OpenAI-compatible (Cursor, Hermes, Codex, SDK)
export OPENAI_API_KEY=sk-ama-YOUR_KEY
export OPENAI_BASE_URL=https://api.aimodelapi.ai/v1
# Model: claude-opus-4-6-bedrock-us  (or claude-opus-4-6)

Optional — only for live web / market data

• TAVILY / EXA keys — Hermes optional web search plugin, not part of ModelAPI billing
• MCP servers — e.g. Tushare, custom quote APIs (client-side)
• Your own scripts — force agents to read script output for A-shares, etc.

Other gateways feel "nothing extra to install" when you ask coding questions — not when you ask for today's SSE index without a data feed. Ask Navigator about "Opus 4.6 parity" or see Integrations → Claude Code.

Prompt caching — save vs Anthropic direct

ModelAPI maps cache_control to Bedrock cachePoint and returns cache_read_input_tokens / cache_creation_input_tokens in every response. Cached reads bill at ~10% of input price upstream; ModelAPI adds 0% markup.

• Put cache_control: { type: "ephemeral" } on system prompts and the last tool definition
• Keep prefixes byte-identical across turns for high hit rate
• Claude Code sends cache breakpoints automatically — reuse sessions for savings
• Optional server auto-cache: set AUTO_CACHE_MIN_TOKENS=1024 on the gateway

Claude Code queue/steer while tools run is client-side CLI behavior — not an API feature. See Integrations → Claude Code.

Harness 怎么用（Phase 2–4）

在 /v1/chat/completions 或 /v1/messages 请求上加 HTTP Header，即可启用：分层路由、会话预算、上下文压缩、精确匹配响应缓存、Fallback。 与 Claude Code 对比见 /harness。

1. 最小示例（Phase 2 分层路由）

curl -sD - https://api.aimodelapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-ama-KEY" \
  -H "x-harness-profile: claude-code-optimal" \
  -H "x-harness-session-id: demo-1" \
  -H "Content-Type: application/json" \
  -d '{"model":"nexus/best-reasoning","messages":[{"role":"user","content":"Run tests on all files"}],"max_tokens":64}'
# 响应头: X-Harness-Task: bulk  X-Harness-Model: nexus/cheapest-west

2. 常用 Header

x-harness-profile: claude-code-optimal | hermes-terminal | openclaw-trader
x-harness-session-id: my-session        # Phase 3 会话预算
x-harness-task: plan|bulk|compress     # 可选，强制任务层
x-harness-budget-usd: 50               # 可选，覆盖默认预算
x-harness-auto-compact: true           # Phase 4 长上下文自动摘要
x-harness-classifier: hybrid           # rules | llm | hybrid（默认）

3. Phase 3 MCP · Phase 4 其它

• MCP: npx -y @aimodelapi/mcp-server（见 /downloads）
• 会话超预算 → HTTP 429；重复问答可能 X-ModelAPI-Cache: HIT
• Opus 失败自动 Fallback → Sonnet → DeepSeek；活别名 claude-sonnet-latest / nexus/best-reasoning 随 catalog 升级

Profiles 详情 · Integrations → Hermes

Hermes 终端 Agent

Hermes 走 /v1/chat/completions（OpenAI 格式）。 ModelAPI 在后台完成 OpenAI ↔ Bedrock 工具格式转换；平台用户走 Bedrock，无需本地 openai-claude 代理。 完整分步：Integrations → Hermes。

推荐 config.yaml

model:
  default: claude-sonnet-latest
  provider: custom
  base_url: https://api.aimodelapi.ai/v1
  api_key: ${OPENAI_API_KEY}   # 非 openai.com 时必须写，否则 401

Harness 补丁（一次性）

Hermes 不会自动发送 x-harness-profile。 仓库 tools/hermes/apply-harness-patch.sh 对 aimodelapi.ai 注入hermes-terminal（Sonnet 默认、$25 会话预算、bulk/compress 分层）。 改配置后 Hermes 内 /new 开新会话。

HTTP 502 / 并行 tool_calls（已修复）

现象：assistant 一次返回多个 tool_calls（如 3 个 terminal curl）后 Hermes 报 502 / Stream error。 原因：Bedrock 要求同一轮所有 toolResult 在一条 user 消息；OpenAI/Hermes 默认发多条 role: tool。 ModelAPI 已在 collectToolResultBlocks 合并。仍报错请确认生产 backend 已部署最新版。

开发者细节见仓库 docs/hermes-integration.md。

API Endpoints

Use the same API key on any host. Check live status on /status.

If the primary host is slow from your network, try us.api.aimodelapi.ai once DNS is live, or watch status for regional PoPs.

Wan 2.7 image API

客户填百炼原厂名 image、wan-2.7-image、wan-2.7-image-Pro 也可以，网关会映射到IMG-bl-wan2.7-image /IMG-bl-wan2.7-image-pro。 文生图、图生图、改图是同一套模型，不是新 SKU。 路径 POST /v1/images/generations 或 POST /v1/images/edits。 若在生图接口误填 WAN-t2v-2.7 / WAN-i2v-2.7，会按生图处理（映射到 IMG-bl-wan2.7-image），不会出视频。

# Text-to-image
curl -sS https://api.aimodelapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-ama-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "IMG-bl-wan2.7-image",
    "prompt": "A ceramic tea cup on a wooden table, soft morning light",
    "n": 1,
    "size": "2K"
  }'

# Image edit / I2I — same model, pass a public image URL (JSON, not multipart)
curl -sS https://api.aimodelapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-ama-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "IMG-bl-wan2.7-image",
    "prompt": "Change the background to a rainy night street",
    "image": "https://example.com/cup.png",
    "size": "2K"
  }'

Optional: n (1–4 with refs), size (1K/2K/4K Pro T2I only), thinking_mode (T2I only). Edit / I2I: image or images (public URL or data URL, max 9; output max 2K). List: GET /v1/models?capability=image. /integrations#image

Video generation API

Video is not OpenAI /v1/videos and not the image endpoint. Use the async Volcengine-style path below. Models in GET /v1/models with available: true still need this route. Wan 2.7 text-to-video ID is WAN-t2v-2.7 (not WAN-t2v, which is 2.5).

Wan model IDs

Request body

Required: model, prompt. Optional: duration (default 5, max 30), resolution (720P / 1080P for 2.7), negative_prompt, first_frame_image (I2V), reference_video (R2V). Auth is the same as images: Authorization: Bearer sk-ama-.... Credits are reserved on submit (402 if balance is too low). Wan tasks cannot be cancelled (405).

Async: submit then poll

POST returns id + status: queued — no MP4 yet. Poll GET until succeeded (content.video_url) or failed.

# Submit Wan 2.7 text-to-video
curl -sS https://api.aimodelapi.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer sk-ama-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "WAN-t2v-2.7",
    "prompt": "A golden retriever running on a beach at sunset, cinematic",
    "duration": 5,
    "resolution": "720P"
  }'
# → {"id":"<task_id>","model":"WAN-t2v-2.7","status":"queued","created_at":...}

# Poll
curl -sS https://api.aimodelapi.ai/v1/contents/generations/tasks/<task_id> \
  -H "Authorization: Bearer sk-ama-YOUR_KEY"
# succeeded → {"status":"succeeded","content":{"video_url":"https://..."}}

# Image-to-video
curl -sS https://api.aimodelapi.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer sk-ama-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "WAN-i2v-2.7",
    "prompt": "Camera slowly pushes in, gentle wind",
    "duration": 5,
    "resolution": "720P",
    "first_frame_image": "https://example.com/first-frame.jpg"
  }'

五步接好 · Connect in order

1. Dashboard → API Keys 复制 sk-ama-...， 先 GET /v1/credits 确认余额（提交时按秒预扣，不足 402）。
2. 模型 ID 用 WAN-t2v-2.7（2.7 文生视频）。WAN-t2v 是 2.5；IMG-bl-wan2.7-image 是生图。
3. 只打 POST /v1/contents/generations/tasks。/v1/videos 会 404。
4. 响应只有 id + queued，还没有 mp4。
5. 每 5–10 秒 GET .../tasks/{id}， 直到 succeeded 再下载 content.video_url。

哪些 Agent 能出视频 · Which agents can produce video

只把 Base URL 填进 Cursor / Claude Code / Hermes 的对话设置，不会自动出片。那些客户端只调用 Chat / Messages。必须再加一层 HTTP 工具打本页接口。

给 Agent / MCP 的 tool 说明（可直接粘贴）：

Name: generate_video
POST https://api.aimodelapi.ai/v1/contents/generations/tasks
Authorization: Bearer $MODELAPI_KEY
JSON: {"model":"WAN-t2v-2.7","prompt":"<user prompt>","duration":5,"resolution":"720P"}
Then GET /v1/contents/generations/tasks/{id} every 8s until succeeded|failed.
Return content.video_url. Never call /v1/videos or /v1/images/generations for WAN-*.

List video models: GET /v1/models?capability=video. Image generation stays on POST /v1/images/generations with IMG-* IDs (e.g. IMG-bl-wan2.7-image). Step-by-step for n8n / Hermes: /integrations#video · /models.

Quickstart

1. Create a free account
2. Go to Dashboard → API Keys and create a key
3. Point your app at https://api.aimodelapi.ai/v1

curl https://api.aimodelapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

OpenAI Compatible

Most OpenAI SDKs and tools work by changing only the base URL and API key.

Base URL: https://api.aimodelapi.ai/v1
API Key:  sk-xxxx (from Dashboard)
Model:    claude-sonnet-latest | glm-5.2 | deepseek-v4-flash | nexus/auto

# Python (OpenAI SDK) — production: timeout ≥180s, max_retries=5
from openai import OpenAI
client = OpenAI(
  api_key="sk-your-key",
  base_url="https://api.aimodelapi.ai/v1",
  timeout=180.0,
  max_retries=5,
)

# Node.js
import OpenAI from "openai";
const client = new OpenAI({
  apiKey: process.env.MODELAPI_KEY,
  baseURL: "https://api.aimodelapi.ai/v1",
});

See also: Integrations for Cursor, Continue, LangChain, and more.

API Troubleshooting

502 / Stream error (Hermes)

Parallel tool_calls in one turn: Bedrock needs merged toolResult blocks — fixed on ModelAPI. Run /new after config changes. See #hermes.

401 Unauthorized

Wrong or incomplete API key. Base URL must end with /v1. Hermes: add api_key: ${OPENAI_API_KEY} in config.yaml for custom base_url. Regenerate key in Dashboard → API Keys.

403 Forbidden

Insufficient balance or model not available on your plan. Top up at Dashboard → Billing.

402 Payment required

Account balance too low. Top up at Dashboard → Billing before production traffic.

429 Rate limit

Free: 20 RPM / 200 RPD. Paid: 500+ RPM. Read HTTP Retry-After or body retry_after_sec, wait, then retry. Harness session budget exceeded also returns 429.

502 / 503 / 504

Temporary unavailability — retry with exponential backoff (up to 5 attempts). Include request_id if contacting support.

Connection timeout

Increase client read timeout (≥180s for agents). Confirm Base URL and check /status. Same key works on all live hosts.

Model not found

Copy exact model ID from /models, or use live aliases: claude-sonnet-latest, claude-opus-latest, nexus/best-reasoning.

Video 404 on /v1/videos

Video is POST /v1/contents/generations/tasks (model=WAN-t2v-2.7), then GET the returned id. See #video. Do not use /v1/videos or put WAN-* on /v1/images/generations.

Cursor no response

Settings → Models: Base URL = https://api.aimodelapi.ai/v1, key = sk-ama-..., add model ID manually.

Still stuck? Open the Navigator widget (bottom-right) or email support@aimodelapi.ai.

CC Switch & IDE routing

Use CC Switch or manual env vars to point OpenAI-compatible tools at ModelAPI. Full step-by-step: Integrations → CC Switch.

# OpenAI-compatible clients (Cursor, Codex CLI, Continue, etc.)
export OPENAI_API_KEY=sk-ama-YOUR_KEY
export OPENAI_BASE_URL=https://api.aimodelapi.ai/v1

# Recommended live aliases (auto-resolve to current Bedrock / catalog)
# claude-sonnet-latest
# claude-opus-latest
# nexus/best-reasoning | nexus/best-coding

Check balance from terminal

Same API key as chat requests. Useful for scripts and CI.

export MODELAPI_KEY=sk-ama-YOUR_KEY
curl -s -H "Authorization: Bearer $MODELAPI_KEY" \
  https://api.aimodelapi.ai/v1/credits | jq '{balance, currency, promotions}'

FAQ

Is this OpenAI?

No. ModelAPI is an independent gateway to 100+ models from OpenAI, Anthropic, Google, DeepSeek, and more — with transparent official pricing.

Can I test before paying?

Yes. Use the free Playground (3 uses/day, no login) or register for dashboard access and top up from $5.

Refund policy?

Credits are non-refundable after top-up. Contact sales@aimodelapi.ai for billing disputes.

Rate limits?

Free tier: 20 RPM / 200 RPD for abuse prevention. Paid customers (after top-up): no platform request caps — only your balance (402) or optional spend cap you set in Settings.

Do you markup token prices?

No hidden token markup. You pay official model rates + 5% infrastructure fee on credit purchase only.

Is GLM-5.2 live?

Yes. Call `glm-5.2` on the same OpenAI-compatible chat endpoint. GLM-5.1 remains available as the previous SKU.

Is Opus 4.6 the same as Claude Code with Anthropic direct?

Same Bedrock Opus 4.6 weights for chat, code, client-side tools, extended thinking, vision, and prompt caching. Anthropic-hosted web search still unavailable on Bedrock — see Model parity above.

Do customers need TAVILY or MCP?

No for normal use. Only if they want agents to fetch live web/market data — same as any provider; not included in the API key.

Partner & Affiliate Copy

Copy-paste for Reddit, Discord, Telegram. Earn 20% on referred top-ups. Apply to partner →

Affordable LLM API for developers & AI bots.
OpenAI-compatible · 100+ models · Official pricing + 5% infra fee.
Starter $5 · Basic $15 · Business $30+
Free playground: https://aimodelapi.ai/playground
Sign up: https://aimodelapi.ai/?ref=YOUR_CODE

#AI #API #LLM #OpenAIalternative

Streaming

Set stream: true in your request body. Responses use Server-Sent Events (SSE) in the standard OpenAI chat completions chunk format, ending with data: [DONE].

• Agent and tool-heavy turns can run longer — set HTTP client read timeout to ≥180 seconds
• On stream errors, check the final SSE line for a JSON error object with request_id
• Production checklist and SDK examples: Production integration

curl -N https://api.aimodelapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-ama-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-latest","messages":[{"role":"user","content":"Hi"}],"stream":true}'