| name | aihubmix-playground |
| description | Try, tune, and compare 500+ AI models on AIHubMix from a coding agent — live model discovery, four wire protocols (Chat Completions/Responses/Messages/Gemini), image/video generation, model comparison on the same prompt, and handoff links that open a preconfigured Playground (playground.aihubmix.com) in the user's browser. Use for Chinese or English requests about trying/testing a model (试用/测试模型), picking the best model for a task (选型/哪个模型好), tuning prompts or parameters (调参/温度/reasoning), comparing models on the same prompt (对比/PK), generating images or video through AIHubMix (文生图/文生视频), or sharing a configured Playground link (深链/链接直达). For integrating AIHubMix into an app or generating SDK code, prefer the aihubmixApi skill; this skill covers the try-tune-compare-handoff loop. |
AIHubMix Playground for Agents
You are operating AIHubMix's model-trial capabilities on behalf of a user. Everything the web Playground (https://playground.aihubmix.com/) can do, you can do through public APIs — and you can hand the user a link that opens the Playground already configured with what you set up.
Follow the steps in order. Do not report success on any step until its verification actually passed.
Ground rules
- Never guess model ids, prices, or parameters from memory. Read them from the live catalog and schemas below. Prices change; ids get delisted.
- HTTP 200 alone is not success. Inspect the response body; truncated or empty content with a 200 is a failure to investigate (check
finish_reason).
- Real calls cost real money. Before running anything beyond a minimal verification call — batches, comparisons, media generation — tell the user the per-call price from the catalog and get their go-ahead.
- Never print the API key into the conversation, files, or command output. Reference it as
$AIHUBMIX_API_KEY only.
Step 1 — Key
test -n "$AIHUBMIX_API_KEY" && echo set || echo missing
If missing, ask the user to create one at https://console.aihubmix.com/ and export it. Do not proceed with a placeholder.
Step 2 — Discover models
Live catalog (no auth), with pricing and metadata:
curl -s "https://aihubmix.com/api/v1/models?type=llm&sort_by=order"
For any candidate model, fetch its guide — pricing, verified capabilities, endpoints, runnable example:
https://aihubmix.com/model/{model_id}/llms.txt
A guide that says "No verified integration guide" means the model is not yet covered by verification — it may still work, but confirm with a minimal real call before recommending it, and prefer covered models when several fit.
Full parameter schemas (types, ranges, enums, defaults) are linked from each guide. Filenames are content-addressed — always follow the link or https://aihubmix.com/model-data/index.json; never compose them by hand.
Step 3 — Call
All four protocols run against https://aihubmix.com:
| Protocol | Endpoint | Auth header |
|---|
| OpenAI Chat Completions | POST /v1/chat/completions | Authorization: Bearer $AIHUBMIX_API_KEY |
| OpenAI Responses | POST /v1/responses | Authorization: Bearer $AIHUBMIX_API_KEY |
| Anthropic Messages | POST /v1/messages | x-api-key: $AIHUBMIX_API_KEY + anthropic-version: 2023-06-01 |
| Google Gemini | POST /gemini/v1beta/models/{model}:generateContent | x-goog-api-key: $AIHUBMIX_API_KEY |
Pick the protocol matching the user's existing code. Only send parameters the model's schema declares — off-schema parameters are either rejected (400) or silently ignored.
Step 4 — Verify end to end
curl -s https://aihubmix.com/v1/chat/completions \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<MODEL_ID>","messages":[{"role":"user","content":"Reply with exactly: AIHubMix is connected"}],"max_tokens":64}'
Success = body contains AIHubMix is connected and model echoes a real id. Keep max_tokens ≥ 64 — tighter budgets truncate the phrase on some models (finish_reason: "length" with a 200), which reads like a failure when the connection is fine.
Comparing models
To compare N models on the same prompt: run the same request against each candidate (sequentially or in parallel), then report per model — output quality (quote the actual outputs), latency you measured, and cost from the catalog. Never invent a number: every figure in your comparison must come from a response you actually received or a price you actually read. Disclose total spend when done.
Image / video generation
Media endpoints live under /ai/v1 and each media model's llms.txt carries its real path and lifecycle:
- Images (
POST /ai/v1/images/generations): usually synchronous — response carries output URLs.
- Video (
POST /ai/v1/videos): asynchronous — response carries a task id; poll GET /ai/v1/videos/{id} until a terminal state (completed / failed / cancelled / timeout).
- Output URLs are short-lived (roughly 30 minutes) and are downloaded with the same
Authorization: Bearer header — fetch promptly and store the content yourself.
- Media pricing is per-generation; read it from the model page before batches.
Handing off to the human — Playground links
When the user wants to continue by hand (tweak parameters, iterate on a prompt visually), generate a link that opens the Playground preconfigured:
- Open N models at once:
https://playground.aihubmix.com/?models=<id1>,<id2>,<id3> (up to 6, one tab per model; the Playground has no side-by-side view, so run comparisons yourself via the API and hand over tabs for the human to inspect)
- Side-by-side spec comparison:
https://aihubmix.com/compare/<id1>/<id2> — the main site renders any two models' specs, pricing, and capabilities side by side; hand this link over when the human wants a visual spec comparison (live-output comparison is your job via the API)
- One configured session:
https://playground.aihubmix.com/?config=<base64url of JSON>
where the JSON is {"model": "<id>", "proto": "chat|messages|responses|gemini", "params": {...}, "system": "...", "draft": "..."} — draft prefills the input box without sending, so the human decides when to fire. Keep the encoded string under 6000 characters; never put keys or secrets in it. All fields except model are optional; unknown fields are ignored.
Give the user the link with one sentence on what it opens. The link is one-shot: parameters vanish from the address bar after loading.
Troubleshooting
Error responses carry a tid (trace id) — quote it when reporting issues. Full mapping: https://docs.aihubmix.com/en/FAQs/HTTP-Codes.md
| Symptom | Likely cause | Fix |
|---|
| 401 | Missing/invalid key, or wrong auth header for the protocol | Re-check Step 1 and the header table in Step 3 |
403 insufficient_user_quota | Insufficient balance | Ask the user to top up at https://console.aihubmix.com/, then re-run Step 4 |
| 400 parameter error | Model doesn't support that parameter (most 400s pass through from the upstream provider) | Re-read the model's schema before retrying |
| 404 on model | Wrong id | Re-read the catalog; never guess ids |
| 429 | Rate limited | Back off and retry |
| 503 | No channel can serve the request, or upstream throttling | Verify the id and account access; retry later |
More
