# Cookbook

> End-to-end, runnable MirAPI tutorials: chat, tools, code review, video, images, RAG, and batch processing — each with runnable code and an approximate cost.

The Cookbook walks through complete tasks, from an empty project to a working result. Every tutorial states its deliverable up front, lists the prerequisites, provides fully runnable code (curl and Python unless noted otherwise), and ends with an approximate cost.

## Conventions used everywhere

All tutorials share the same setup. Skim it once so the per-tutorial code stays short.

- **API key** — `MIRAPI_API_KEY`, created in https://console.mirapi.ai → **API Keys**. Send it as `Authorization: Bearer <key>` (OpenAI protocol), `x-api-key: <key>` (Anthropic protocol), or `x-goog-api-key: <key>` (Gemini protocol).
- **Model** — `deepseek-chat`, the exact `id` returned by `GET /v1/models`. Switch models by changing one string.
- **Balance** — prepaid and non-expiring. An empty balance returns **403**; topping up restores the same key immediately.
- **Streaming** — streaming uses standard SSE: `data:` lines, terminated by `data: [DONE]`; reasoning content arrives before the answer.

### Base URLs per protocol

| Protocol | Base URL | Auth header |
|---|---|---|
| OpenAI | `https://api.mirapi.ai/v1` | `Authorization: Bearer` |
| Anthropic | `https://api.mirapi.ai` | `x-api-key` or `Authorization: Bearer` |
| Gemini | `https://api.mirapi.ai` or `https://api.mirapi.ai/v1beta` | `x-goog-api-key` or `?key=` |

Rule of thumb: if your tool appends its own path after the base URL (such as `/chat/completions`), use `https://api.mirapi.ai/v1`.

### Error codes at a glance

- **401** — the key is missing, invalid, or unknown; fix the credentials.
- **403** — the key is valid but rejected: insufficient balance, model not whitelisted, quota, or IP allowlist.
- **413** — the request is too large; reduce its size.
- **429** — rate limited; retry with jittered exponential backoff (1s → 2s → 4s, capped at ~30s). There is no `Retry-After` header.
- **500** — a transient upstream or gateway failure; idempotent requests are safe to retry.

Every error message ends with a request ID — include it in any support ticket.

## Tutorials

| # | Tutorial | You end up with |
|---|---|---|
| 1 | [First integration](/docs/tutorials/first-integration) | A one-file Python script that streams a chat completion |
| 2 | [Migrate in one prompt](/docs/tutorials/migrate-in-one-prompt) | An existing project pointed at MirAPI by Claude Code or Cursor, plus a verification checklist |
| 3 | [Tool-calling agent](/docs/tutorials/tool-calling-agent) | A complete function-calling loop: define → call → execute → feed back → final answer |
| 4 | [Automatic code review](/docs/tutorials/auto-code-review) | A Claude Code Stop hook that runs a Codex review on every finished message |
| 5 | [Claude Code advanced](/docs/tutorials/claude-code-advanced) | settings.json, hooks, model switching, and a spend cap via the key's quota |
| 6 | [CI code review](/docs/tutorials/ci-code-review) | A GitHub Actions job that reviews every pull request and posts the result |
| 7 | [Text-to-video](/docs/tutorials/text-to-video) | A complete submit → poll → download script with timeout and failure branches |
| 8 | [Image-to-video](/docs/tutorials/image-to-video) | First-frame control for video generation |
| 9 | [Image generation](/docs/tutorials/image-generation) | Generate and edit images, saved to disk |
| 10 | [RAG](/docs/tutorials/rag) | A single-file retrieval pipeline: embeddings → recall → rerank → cited answer |
| 11 | [Batch processing](/docs/tutorials/batch-processing) | A rate-limited, resumable async batch translator for a CSV |

## Cost notes

Every tutorial ends with an approximate cost. The exact amount depends on the model and input/output length, and the authoritative sources are the console usage log plus `GET /api/log/token` for per-request detail and `GET /api/usage/token` for account totals. Non-streaming responses report only token counts — never an amount — so reconcile against those endpoints.

## Related links

- [Quickstart](/docs/quickstart) — the five-minute path to your first request.
- [Models & pricing](/docs/models) — browse the catalogue and understand pricing.
- [Configuration](/docs/configuration) — base URLs, auth, parameters, and errors in full.
- [FAQ](/docs/faq) — common questions about keys, billing, and limits.