# AIHubMix for Agents

You are (probably) an AI coding agent whose user wants to call AI models through AIHubMix. This page is written for you. Follow the steps in order, and do not tell the user the setup succeeded until the verification step in Step 4 actually passes.

AIHubMix is a unified model gateway: one API key, 500+ models (OpenAI, Anthropic, Google, and leading open-source providers), four wire protocols. Machine-readable index: https://aihubmix.com/llms.txt

## Step 1 — Get the API key

1. Check the environment first: `echo ${AIHUBMIX_API_KEY:+set}`.
2. If it is not set, ask the user to create a key at https://console.aihubmix.com/ and export it as `AIHUBMIX_API_KEY`. Do not proceed with a placeholder value.
3. Never print the full key into the conversation, files, or command output. Reference it only as `$AIHUBMIX_API_KEY`.

## Step 2 — Pick a model

The catalog is public (no auth):

```bash
curl -s "https://aihubmix.com/api/v1/models?type=llm&sort_by=order"
```

Use a real model id from this response. Do not guess model ids from memory, and do not quote prices from memory — read them from the catalog. Per-model parameter schemas are also public at https://aihubmix.com/model-data/index.json (follow each entry's `path`).

Note: a model appearing in the public catalog does not guarantee this account can call it. Step 4 is what proves the account + model combination works.

## Step 3 — Call the API

Pick the protocol that matches the SDK or code you are integrating. All four 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` |

Existing OpenAI/Anthropic/Gemini SDK code needs only two changes: point the base URL at `https://aihubmix.com` (Gemini: `https://aihubmix.com/gemini`) and swap the key.

## Step 4 — Verify end to end

Run one harmless request with a model id you picked in Step 2:

```bash
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 means the response body contains `AIHubMix is connected` and the `model` field echoes a real model. An HTTP 200 alone is not success — inspect the body. Keep `max_tokens` at 64 or higher: tighter budgets truncate the phrase on some models (`finish_reason: "length"` with a 200), which reads like a failure when the connection is actually fine. If verification fails, fix the specific error (table below) and re-run; only then report success to the user.

## Media generation (images / video)

Unified endpoints live under `/ai/v1` (e.g. `POST /ai/v1/images/generations`, `POST /ai/v1/videos` then poll `GET /ai/v1/videos/{id}`). Video is asynchronous: submit, then poll until a terminal state. See [Image generation](https://docs.aihubmix.com/en/api/Image-Gen.md) and [Async tasks](https://docs.aihubmix.com/en/api/async-tasks.md). Generation costs real money — tell the user the price (from the catalog) before running batches.

## 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 column 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 |
| 403 (other) | Key not allowed to use this model, IP restriction, or account suspended | Check the key's model/IP restrictions in the console |
| 400 with parameter error | Model does not support that parameter (most 400s are passed through from the upstream provider) | Check the model's schema at `/model-data/` before retrying |
| 404 on model | Wrong model id | Re-read the catalog from Step 2; never guess ids |
| 429 | Rate limited | Back off and retry |
| 503 | No channel can serve the request (wrong id / no access), or upstream provider throttling | Verify the id and your access; retry later |

## Going further

- Install the AIHubMix skill for richer workflows (live model comparison, key doctor, example generation): https://docs.aihubmix.com/en/skills.md ([repo](https://github.com/AIhubmix/skills))
- For the try-tune-compare loop (model trials, side-by-side comparison, media generation, preconfigured Playground links), fetch the Playground skill and follow it: `curl -fsSL https://aihubmix.com/skills/playground`
- Generate integration code programmatically: npm [`@aihubmix/codegen`](https://www.npmjs.com/package/@aihubmix/codegen) — 4 protocols × 7 languages from one config, media endpoints included. It is the generator behind the Playground's "Get Code", and the body it builds is the exact wire body the Playground sends. Pair with [`@aihubmix/model-schema`](https://www.npmjs.com/package/@aihubmix/model-schema) to feed it canon parameter schemas
- Gateway features that need zero client changes: [model mapping & fallback](https://docs.aihubmix.com/en/api/Model-Mapping-Fallback.md), [smart routing with `model: "auto"`](https://docs.aihubmix.com/en/api/llm-router.md), [structured output repair](https://docs.aihubmix.com/en/api/structured-output-repair.md)
- Human-facing playground: https://playground.aihubmix.com/ (deep link `?model={model_id}`)
- Human-facing compare page: `https://aihubmix.com/compare/{model_a}/{model_b}` — side-by-side specs and pricing for any two models; hand it over when the user wants a visual comparison
- Full docs index: https://docs.aihubmix.com/llms.txt (append `.md` to any docs URL for plain markdown)