Bootstrap a modular AllToken agent — chat, async image+video, model routing, OpenAI-compatible SDK. Works inside Hermes, OpenClaw, Claude Code, Codex CLI, OpenCode, or any runtime that loads SKILL.md.
This skill helps you create a modular AI agent powered by AllToken — a unified, OpenAI-compatible API with access to leading language, image, and video models behind one endpoint, plus automatic provider fallbacks and cost-effective routing.
Designed to be invoked from Hermes, OpenClaw, Claude Code, Codex CLI, or any other agent runtime that consumes skills.
Standalone Agent Core — runs independently, extensible via hooks
OpenAI SDK compatible — change two settings and you're done
Multi-modal — chat, image (async), video (async) on one key
Compatibility: OpenAI-compatible — any OpenAI SDK works by overriding base_url/baseURL.
Coverage:
POST /chat/completions — chat (streaming, tool calls, thinking, web search)
GET /models — OpenAI-compatible model list
POST /images/generations/async + GET /images/generations/{id} — async image generation
POST /videos/generations + GET /videos/generations/{id} — async video generation
GET /api-account/models / /{model_path} / /filters — full catalog with pricing and capabilities (public, no auth required)
GET /api-account/providers (+ /{id}/stats) — providers, health, throughput (public)
GET /api-account/rankings/all — leaderboards, benchmarks, speed rankings (public)
GET /api-account/health/{routes,summary} — route health & availability (public)
GET /api-account/user/{api-keys,usage,billing,balance} — web-session token only, not callable with your Bearer API key (you'll get 401 auth_error / invalid_token). Manage these in Settings → API Keys / Billing on https://alltoken.ai.
Project Setup
Step 1 — Initialize project
bash
mkdir my-alltoken-agent && cd my-alltoken-agent
npm init -y
npm pkg set type="module"
Create src/client.ts. AllToken is OpenAI-compatible; we just override the base URL.
typescript
import OpenAI from 'openai';
export function createAllTokenClient(apiKey = process.env.ALLTOKEN_API_KEY): OpenAI {
if (!apiKey) throw new Error('ALLTOKEN_API_KEY is not set');
return new OpenAI({
apiKey,
baseURL: 'https://api.alltoken.ai/v1',
});
}
Step 2 — Agent Core with Hooks
Create src/agent.ts — the standalone agent. It streams via OpenAI's SSE protocol and emits typed events for any UI to consume.
Persist b64_json to disk in one shot — re-polling a delivered image returns 410 image_already_retrieved and the result is gone. The 410 envelope:
json
{"error":{"code":"image_already_retrieved","message":"Image data was already retrieved; please submit a new generation request","request_id":"...","type":"invalid_request_error"}}
Observed latencies (use these to size your retry budget, not as SLAs):
Image gpt-image-2 1024×1024 quality=low: ~15–25 s end-to-end (verified 20.6 s on a real submit).
Image quality=high or 1536×1024: 30–60 s per docs.
Video seedance-1.5-pro 5 s @ 480 p: 30–120 s typical; 1080 p can take 3–5 min.
Recommended poll interval: 2 s for images, 3 s for videos.
Submit-response fields (the full shape, not just id):
After status==completed, the GET adds: data: [{b64_json}], usage: {input_tokens, output_tokens, total_tokens, input_tokens_details}, size, quality, output_format, completed_at, expires_at. Note: revised_prompt is not present in current responses despite appearing in the docs example — treat it as optional.
Step 5 — Headless usage
Create src/headless.ts:
typescript
import { createAgent } from './agent.js';
import { defaultTools } from './tools.js';
import { generateImage } from './media.js';
import { writeFile } from 'node:fs/promises';
async function main() {
const agent = createAgent({
model: 'minimax-m2.7',
instructions: 'You are a helpful assistant with tools.',
tools: defaultTools,
enableSearch: false,
});
agent.on('thinking:start', () => console.log('\n🤔 Thinking...'));
agent.on('tool:call', (name, args) => console.log(`🔧 ${name}`, args));
agent.on('stream:delta', (delta) => process.stdout.write(delta));
agent.on('stream:end', () => console.log());
agent.on('error', (e) => console.error('❌', e.message));
// Chat
await agent.send('What time is it in Tokyo?');
// Image (async)
const img = await generateImage({
prompt: 'A clean studio product photo of a glass teapot on a walnut table',
size: '1024x1024',
quality: 'high',
});
if (img.status === 'completed' && img.data?.[0]?.b64_json) {
await writeFile('teapot.png', Buffer.from(img.data[0].b64_json, 'base64'));
console.log('\n💾 Saved teapot.png');
}
}
main().catch(console.error);
Run: ALLTOKEN_API_KEY=sk-... npm run start:headless
Step 6 — Optional Ink TUI
Create src/cli.tsx for a terminal chat UI. Subscribe to stream:delta and tool:call events from the agent and render them. The agent core is UI-agnostic — the same instance can power Hermes, OpenClaw, Discord, or HTTP.
For Python users — including those embedding the agent inside Hermes or OpenClaw Python tools:
python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ALLTOKEN_API_KEY"],
base_url="https://api.alltoken.ai/v1",
)
# Streaming chat
stream = client.chat.completions.create(
model="minimax-m2.7",
messages=[{"role": "user", "content": "Explain SSE in one sentence."}],
stream=True,
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print()
Async image (poll loop):
python
import os, time, base64, uuid, requests
BASE = "https://api.alltoken.ai/v1"
H = {"Authorization": f"Bearer {os.environ['ALLTOKEN_API_KEY']}", "Content-Type": "application/json"}
task = requests.post(
f"{BASE}/images/generations/async",
headers={**H, "Idempotency-Key": str(uuid.uuid4())},
json={"model": "gpt-image-2", "prompt": "A cat astronaut, studio light", "size": "1024x1024", "quality": "high"},
).json()
while True:
res = requests.get(f"{BASE}/images/generations/{task['id']}", headers=H).json()
if res["status"] in ("completed", "failed", "cancelled"):
break
time.sleep(2)
if res["status"] == "completed":
with open("cat.png", "wb") as f:
f.write(base64.b64decode(res["data"][0]["b64_json"]))
Using AllToken from inside Hermes / OpenClaw
Both Hermes and OpenClaw load skills from SKILL.md files and can run TypeScript or Python tools at the agent boundary. There are two integration patterns:
Pattern A — AllToken as your agent's model provider
Point your host agent's HTTP client at AllToken. In OpenClaw / Hermes config, set:
No code changes needed — the OpenAI-compatible endpoint accepts the same requests.
Pattern B — AllToken as a tool inside another agent
Drop the agent.ts / media.ts modules into the host agent's tools directory and expose them as callable tools (chat, generate_image, generate_video). The host agent (running on any model) then delegates multimodal work to AllToken on demand.
Available chat models on a fresh key: 38 as of this writing. Image: 1. Video: 7.
Do not hardcode model IDs in production — the catalog evolves. Use the live endpoints:
typescript
// OpenAI-compatible list (good for SDK clients)
const list = await fetch('https://api.alltoken.ai/v1/models', {
headers: { Authorization: `Bearer ${process.env.ALLTOKEN_API_KEY}` },
}).then((r) => r.json());
// Rich catalog with pricing, capabilities, tags (used by the website)
const catalog = await fetch('https://api.alltoken.ai/api-account/models').then((r) => r.json());
// Single model detail page
const detail = await fetch('https://api.alltoken.ai/api-account/models/gpt-5.4').then((r) => r.json());
Pair with the Rankings API (GET /api-account/rankings/all) for live leaderboards by usage, benchmarks, throughput, and category leaders — useful for --auto model selection.
Routing & fallbacks
AllToken handles provider routing internally. Two knobs:
Account-level default routing — set routing_mode (code or manual), allowed_models, and a default_models priority list on each API key:
text
POST /api-account/user/api-keys
PUT /api-account/user/api-keys/{key_id}/default-models
Per-request override — pass the exact model ID in the request body to bypass routing for that call.
When a provider returns 502/503, AllToken may automatically fall back to the next provider for the model.
Web search (enable_search)
Pass enable_search: true on a chat completion to opt into AllToken's unified web-search backend. Support is per-provider, not per-request shape — same flag, different effective behavior across model families. Live probe on 2026-05-12 (asking "current Bitcoin price"):
Family
Outcome
Notes
DeepSeek (deepseek-v3.2, deepseek-v4-pro)
✅ Searches
Returns fresh prices with timestamps
Qwen (qwen3.6-flash, qwen3.6-max-preview)
✅ Searches
Same fresh data via the unified backend
Claude (claude-opus-4-7, claude-sonnet-4-6)
❌ Silently ignores
Model responds "I don't have web search"
GLM (glm-5, glm-5.1)
❌ Silently ignores
Same as Claude
Kimi (kimi-k2.6)
❌ Silently ignores
Minimax (minimax-m2.7)
❌ Silently ignores
Gemini (gemini-3.1-pro-preview)
⚠️ Empty / refusal
Inconsistent — re-test before relying
OpenAI (gpt-5.4, gpt-5.4-nano, gpt-5.5)
🔴 HTTP 503 all_providers_failed
Upstream rejects the flag
Recommendation: when you need search, default to a DeepSeek or Qwen model. If you're on a different family, fall back to a function-calling pattern (model emits a tool call → your tool hits a search API → you re-invoke). The enable_search matrix above is empirical and provider-side support may change — re-test for critical paths.
Note: AllToken does not include search-result citations in the response annotations[] field today, so detecting "did search fire" requires latency heuristics (typically +6 – 15 s vs no-search baseline) or content sniffing for fresh facts.
Health, rate limits, errors
Per-key rate limits: set rpm_limit, tpm_limit, monthly_quota, credit_limit when creating the key.
Status codes you should handle:400 invalid params · 401 bad key · 402 insufficient balance · 403 forbidden · 404 not found · 429 rate limited (respect Retry-After) · 5xx upstream — already retried server-side when safe.
Error envelope (real wire format):json
{
"error": {
"code": "invalid_api_key",
"message": "Invalid or revoked API key",
"param": null,
"type": "auth_error",
"request_id": "d81itf8gdg1fp5ko4bjg"
}
}
Note: code is a string slug (e.g. "invalid_api_key", "image_already_retrieved", "all_providers_failed"), not the numeric HTTP status. type groups errors (auth_error, invalid_request_error, api_error, …). Include request_id when filing support tickets.
Python error-dispatch helper:
python
import json, time, urllib.request, urllib.error
def call(req):
try:
return urllib.request.urlopen(req, timeout=60)
except urllib.error.HTTPError as e:
body = e.read()
try:
err = json.loads(body).get("error", {})
except Exception:
err = {}
retry_after = e.headers.get("Retry-After") # integer seconds (AllToken format)
if e.code == 429 and retry_after:
time.sleep(int(retry_after))
return call(req) # one retry
if e.code == 401: raise RuntimeError(f"auth: {err.get('code')} — rotate API key")
if e.code == 402: raise RuntimeError(f"top up credits: {err.get('message')}")
if e.code == 410 and err.get("code") == "image_already_retrieved":
raise RuntimeError("re-submit; image was already delivered")
if 500 <= e.code < 600 and err.get("code") == "all_providers_failed":
raise RuntimeError("upstream — try fallback model or retry with jitter")
raise RuntimeError(f"{e.code} {err.get('type')}/{err.get('code')}: {err.get('message')} [req={err.get('request_id')}]")
Retry-After is sent as integer seconds. Always combine an explicit retry-after read with exponential backoff (+ jitter) as the fallback when the header is missing.
Health dashboard:GET /api-account/health/summary (returns {"data": {...}} envelope) and /health/routes show live availability, p50/p95 latency, and incident routes — wire this into your runbook.
Cost tracking & budgets
Per-request cost: every chat response includes a usage block:
Capture usage from a streaming response: pass stream_options: {"include_usage": true}. The final data: chunk before data: [DONE] will have choices: [] and the populated usage. Without this option, usage is null on every streamed chunk.
python
stream = client.chat.completions.create(
model="gpt-5.4-nano", messages=[...], stream=True,
stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if chunk.usage is not None:
usage = chunk.usage # only present on the terminal chunk
Per-request cost telemetry (vendor extension): AllToken also emits one extra SSE comment lineafterdata: [DONE] with a fiat-priced breakdown:
Standard OpenAI SDKs drop comment lines (lines beginning with :), so this is invisible when using openai. To capture it, parse the raw SSE stream yourself and do not stop on [DONE]:
python
# stdlib-only — captures both usage (from data: chunks) AND cost comment (post-DONE)
import urllib.request, json
req = urllib.request.Request(URL, data=BODY, method="POST", headers=H)
r = urllib.request.urlopen(req)
saw_done = False
for raw in iter(r.readline, b""):
line = raw.decode().rstrip("\n")
if line.startswith(":"):
cost = json.loads(line[1:]) # {"cost": "...", ...}
elif line.startswith("data: "):
data = line[6:]
if data == "[DONE]": saw_done = True; continue
# ... parse chunk
Other useful response metadata: chat responses also carry top-level service_tier (e.g. "default") and x-gateway-request-id (use this when filing support tickets).
Account-wide totals:/api-account/user/{balance,billing,usage,billing/orders,...} exist but are not callable with the API key — they need the web-session token. Check balance and history in Settings → Billing on https://alltoken.ai, or top up via the same dashboard.