For AI agents

The operating guide for coding agents and assistants that set up and use the API for a person.

This page is written for AI agents (Claude Code, Codex, Cursor, opencode, OpenClaw, Hermes, pi, ChatGPT, Claude). People can read it too. The short version is the site's llms.txt; this page is the full set of rules. Every docs page has a Markdown copy at its URL plus .md, every model has one at https://pinerouter.ai/docs/models/<model id>.md, and the whole docs are in one file at llms-full.txt.

1. Set up

Work out where you run first; the setups differ.

Where you run	What to do
Hosted assistant (claude.ai, ChatGPT)	Install nothing. Ask the person to add `https://pinerouter.ai/mcp` as a custom connector and sign in. No key needed. Stop there.
Coding agent on the person's machine	Get a key, store it, check it, connect your tool (below).
Sandbox with restricted network	If `https://pinerouter.ai` does not answer (proxy 403, DNS failure, timeout), say the address is blocked by the network policy and offer the connector or a normal machine. Do not try other hosts.

For a coding agent:

Ask the person to sign up at https://pinerouter.ai/sign-up, add credit in Wallet, create a key in API keys and paste it to you. Suggest a spending limit on the key.
Store it as API_KEY in the shell profile or a git-ignored .env. Never print it in full, never commit it, never send it anywhere except https://pinerouter.ai.
Check it: curl -s https://pinerouter.ai/v1/models -H "Authorization: Bearer $API_KEY" returns the models the key may use.
Connect your tool to the MCP server, or point your SDK at https://pinerouter.ai/v1 (OpenAI) or https://pinerouter.ai (Anthropic). App guides: Claude Code, Codex CLI, Cherry Studio.
Make one cheap call to prove it works, report its cost, and tell the person what they can now do.

2. Choose a model

Use the exact model id from Models or GET /v1/models. Do not use an id remembered from elsewhere; ids here can differ from the maker's.
Read the model's .md file before a media call: it lists every input field, its options and default, and the price for each setting.
For text, pick by job: a fast cheap model for drafts, classification and background tasks; a strong model for reasoning and code.
For media, the price depends on the settings (resolution, duration, count). Choose the cheapest settings that meet the request, and say which you chose.

3. Call it

Job	Endpoint
Chat, OpenAI format	`POST /v1/chat/completions`
OpenAI Responses (Codex)	`POST /v1/responses`
Anthropic Messages (Claude Code, Anthropic SDK)	`POST /v1/messages`
Any media model with all its settings	`POST /v1/jobs`, then `GET /v1/jobs/<id>` or a webhook
Upload an input file	`POST /v1/files` (multipart `file`), use the returned `url`
Images, OpenAI format	`POST /v1/images/generations`, `POST /v1/images/edits`
Video, OpenAI format	`POST /v1/videos`, `GET /v1/videos/<id>`
Speech and transcription	`POST /v1/audio/speech`, `POST /v1/audio/transcriptions`
Embeddings	`POST /v1/embeddings`

Full request and response shapes: API reference or openapi.json.

Jobs are asynchronous. Start one and keep data.id. If you can receive HTTPS calls, pass webhook_url; otherwise poll GET /v1/jobs/<id> every 5 to 10 seconds (not faster). Stop on succeeded (links in data.outputs) or failed (reason in data.error). Images usually take under a minute, video a few minutes. If a job is still running after 15 minutes, tell the person and keep the id; do not start a second copy.

Files go in as https:// links: a public link, or upload with POST /v1/files (kept 1 day). Results are kept 7 days: download what the person wants to keep and save it where they expect it.

4. Money

The account is prepaid. Text is charged per token after the reply. A media job reserves its expected cost plus 20% when it starts and is charged the real cost when it finishes. A failed job costs nothing.
Before anything that costs more than a few cents (a video, a batch, a loop over many inputs), tell the person the expected total from the model's price table and wait for their yes. Keep a running total and stop before it passes what they agreed.
Check the balance with GET /v1/dashboard/billing/subscription or MCP get_balance; spending with GET /v1/dashboard/billing/usage.
After work that cost money, report what it cost.
A 403 for balance means stop and ask the person to top up. Do not retry.

5. Errors and retries

Status	Meaning	What you do
400	Invalid request, or the content rules refused it	Fix the request using the model's fields. A content refusal is final: do not retry or reword around it.
401	Missing or wrong key	Check the header. Ask the person for a new key if needed.
403	Balance too low, or the key may not use this model	Ask the person to top up or change the key's settings.
429	Rate limit: 120 requests a minute, 60 successful	Wait, then retry with exponential backoff (2, 4, 8 seconds).
500, 502, 503	The model failed or we are briefly busy	Retry up to 3 times with backoff. A failed job is not charged.

Never retry a job that is still running: poll it. Retrying a started job runs and charges it twice.

6. Rules

Safety filters are always on. Sexual content involving minors is refused, and repeated refusals disable the account.
Keep keys out of code, logs, screenshots and chat replies.
Use the person's money as you would your own: the cheapest model and settings that do the job.
If something is unclear, wrong or slow, tell the person and point them to support.

Building it into a product

Call the API from your backend, never from a browser or mobile app (the key would leak). Give each of your customers their own key with a spending limit and allowed models, so one customer cannot spend another's balance.