# For AI agents

> Everything an AI agent needs to use this API without guessing. Hand this page to yours.

Source: https://docs.nocamclub.com/for-ai-agents

![A purple character gives a high five to a small white robot on a rooftop at night. Made with this API.](https://docs.nocamclub.com/examples/agents.jpg)

This page is for the model doing the work. If you're a person, paste the prompt below into your agent, and it will take it from there.

## Hand it to your agent

```text
Use the NoCam API to make photos, videos and text.
Read https://docs.nocamclub.com/llms.txt first, and follow the rules on https://docs.nocamclub.com/for-ai-agents.md
My key is in the NOCAM_API_KEY environment variable. Never print it.
Before spending more than 100 credits in one go, tell me the price and wait for my yes.
```

## What to read

| What | Address |
|---|---|
| The map: every page in one line | [/llms.txt](https://docs.nocamclub.com/llms.txt) |
| Everything in one file | [/llms-full.txt](https://docs.nocamclub.com/llms-full.txt) |
| Any page as Markdown | Add `.md`: [/api/generations.md](https://docs.nocamclub.com/api/generations.md) |
| The API as OpenAPI 3.1 | [/openapi.json](https://docs.nocamclub.com/openapi.json), also at `https://api.nocamclub.com/v1/openapi.json` |
| What's on sale right now, with options and prices | `GET https://api.nocamclub.com/v1/models` |
| A skill file for Claude Code and similar agents | [/skills/nocam/SKILL.md](https://docs.nocamclub.com/skills/nocam/SKILL.md) |

## The rules

1. **Don't guess a model's options.** They differ from model to model, and they change with what's on sale. Read `GET /v1/models/{id}`: `input_schema` is the truth, and `prices` lists what can be bought right now. An unknown field is refused, not ignored.
2. **Check before you spend.** `POST /v1/estimate` takes the same body as `POST /v1/generations`, checks everything and gives the price. Nothing runs and nothing is charged.
3. **Always send an `Idempotency-Key`.** Use a new one for each thing you want made, and the same one when you retry it. Then a timeout can't make you pay twice.
4. **Don't start something again to check on it.** Starting is `POST`, and it costs money. Checking is `GET /v1/generations/{id}`, and it's free. Keep the `id`.
5. **Photos: use `Prefer: wait=60`. Videos: poll.** Photos usually finish within a minute. Videos take minutes, so poll every `poll_after_ms`.
6. **Read `error.code` and act on it.** Every error, on a refused call and on a failed generation alike, has `hint` (what to do) and `retryable` (whether the same request can work: on a failed generation, send it with a new `Idempotency-Key`). `docs_url` has more, but you don't need it to decide.
7. **Check `status`, not just the HTTP code.** A generation that fails while you wait with `Prefer: wait` still answers `200`, with `status: "failed"`.
8. **Tell the person when something was refused.** Don't reword a refused prompt to slip past the rules. Refusals count, and twenty in a day pause the account.
9. **Download what should last.** Result links stop working at `expires_at`, 7 days by default. Uploaded files go after 48 hours.
10. **Never top up on your own.** On `insufficient_credits`, send the person to `top_up_url`.
11. **Never print or commit the key.** Read it from the environment.

## The flow

```text
GET  /v1/models                 What's on sale?
GET  /v1/models/{id}            What does this model take, and what does it cost?
POST /v1/uploads                Files: pass {url}, or get a link to PUT to
POST /v1/estimate               Is this valid, and what's the price?
POST /v1/generations            Start. Charged now. Send Idempotency-Key.
GET  /v1/generations/{id}       Until status is succeeded, failed or canceled.
```

`status` goes `queued` → `running` → `succeeded`, `failed` or `canceled`. A generation that fails or is canceled gives its credits back by itself: don't try to claim them.

## What to do with an error

In short, with the same meaning as `retryable` and `hint`:

| What you see | What it means | What to do |
|---|---|---|
| `invalid_parameter` | A field is wrong. `path` names it and `hint` lists what works | Fix it and send again |
| `unknown_model`, `not_for_sale`, `no_route` | Not available with these settings | Pick from `prices` in `GET /v1/models/{id}`, or another model |
| `input_refused`, `content_refused` | Against the [content rules](https://docs.nocamclub.com/rules.md), or the model refused | Tell the person. Change the idea, don't reword around it |
| `insufficient_credits`, `spend_limit_reached` | Out of credits or over a limit | Tell the person. Send them to `top_up_url` |
| `rate_limited`, `too_many_active` | Too fast or too many at once | Wait for `Retry-After`, then send the same request |
| `provider_unavailable`, `generation_failed` | The model failed. Credits are back | Try once more with a **new** key, then another model |
| `timed_out` | We stopped waiting. Credits are back | Check the same `id` later: the result may still come, free |
| `internal` | Our fault | Retry with the **same** `Idempotency-Key` |
| `invalid_api_key`, `missing_scope`, `account_suspended` | The key or the account | Stop and tell the person |

All of them: [Errors](https://docs.nocamclub.com/errors.md).

## Which model

Short version below. Details and prompt tips are on each model's page, starting at [Models](https://docs.nocamclub.com/models.md).

| The job | Use |
|---|---|
| A photo of someone or something from one photo, cheap and good | `nano-banana-2` |
| The same character across many photos | `nano-banana-pro` |
| A poster or anything with exact words on it | `gpt-image-2` |
| Many reference photos at once, cheap | `seedream-5.0-flash` |
| A photo from text alone, as cheap as it gets | `grok-imagine` |
| A talking clip from one photo, 10 seconds with sound, nearly free | `muse-video` |
| A short clip from a photo or text, or changing a clip you have | `omni-flash` |
| The best clip, up to 30 s, with photos, video and audio as references | `seedance-2.5` |
| The same, cheaper, up to 15 s | `seedance-2.0-fast` |
| A text answer | `gpt-6-luna`, or `claude-opus-5.5` for harder work |

Always confirm a model is on sale with `GET /v1/models` before relying on this table.

## Writing prompts

- **Name your files.** `img1`, `img2`, `video1`, `audio1`, in the order you sent them. See [Files in prompts](https://docs.nocamclub.com/api/files-in-prompts.md).
- **Say what to keep and what to change.** Models tend to carry over anything you don't mention, like the background and the clothes in a photo.
- **Put speech in quotes**, and keep it short enough to say in the clip's length: about 2 words a second.
- **Ask for simple movement.** One action, a still camera. Complicated physics is where clips break.
- **Spell out exact words.** For text in a photo, write the words and add that the spelling must be exact.

## Connecting through MCP

If your client speaks MCP, you don't need to write any HTTP. See [MCP](https://docs.nocamclub.com/mcp.md). A tool's error comes back as a result you can read, with the same codes and hints.

## Testing without spending

A `nc_test_…` key runs the whole API on sample results at no cost, and the word `fail` in a prompt makes the generation fail so you can test your error handling. See [Sandbox](https://docs.nocamclub.com/sandbox.md).