# Generation

URL: https://www.atmee.ai/docs/v2/api/generation

> Make what an avatar or a video needs: portraits from a description, an enhanced or restyled photo, a designed voice, or a short video clip. Paid per call, charged only when something comes back.

Four calls make media for you. Each one is paid, and charged only when at least one result comes
back.

| Call                                                                                    | You send                                    | You get back                            | Guide                                                       |
| --------------------------------------------------------------------------------------- | ------------------------------------------- | --------------------------------------- | ----------------------------------------------------------- |
| [`POST /v1/generation/portraits`](/docs/v2/api/reference/generation/generatePortraits)  | A description of an invented character      | Up to four portraits                    | [Portraits and enhancement](/docs/v2/api/generation/images) |
| [`POST /v1/generation/enhancements`](/docs/v2/api/reference/generation/enhancePortrait) | A photo, and optionally how to restyle it   | Up to four portraits of the same person | [Portraits and enhancement](/docs/v2/api/generation/images) |
| [`POST /v1/generation/voices`](/docs/v2/api/reference/generation/designVoice)           | A description of how the voice should sound | Voice previews of 10 to 60 seconds      | [Voice design](/docs/v2/api/generation/voices)              |
| [`POST /v1/generation/clips`](/docs/v2/api/reference/generation/generateClip)           | An image and a prompt, audio optional       | An mp4 of up to 15 seconds              | [Video generation](/docs/v2/api/generation/video)           |

Portraits, enhancements and voices make what an avatar is built from; pass the result straight to
[Create an avatar](/docs/v2/api/create-avatar). A clip needs no avatar at all.

## What every call has in common

* **A key with two scopes:** `generation:write` and `avatars:write`. Without both, the call
  answers `403 insufficient_scope`. See [API keys](/docs/v2/api/api-keys).
* **An `Idempotency-Key` header** with a new UUID for each new request. Sending the same request
  again with the same key never charges twice: it returns the first result with `replayed: true`.
  Reuse a key only to retry identical inputs; any change needs a new key.
* **Results come back as uploads.** Each output is `upload:<uploadId>`, which works once, for one
  avatar, and expires 24 hours after it was made, with a short-lived `url` to view, play or
  download it. Save what you want to keep straight away.
* **You pay only for results.** A flagged, failed or refused call costs nothing, and so does a
  replay. Each answer's `microcreditsCharged` says what the call cost, in hundredths of a credit
  (`100` is 1 credit), and `GET /v1/account` lists each call's price under `pricing.generation`.
* **Inputs are moderated first.** Descriptions, prompts, sample text and photos are checked before
  anything is made; a flagged input answers `moderation_flagged` and costs nothing.
* **Never make a real person from a description.** For a real person, enhance their own photo,
  with their permission.

## Errors

| Status | `error`                                             | What to do                                                                                          |
| ------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_input`                                     | Fix the field it names. Also an `Idempotency-Key` that isn't a UUID, or was used with other inputs. |
| `400`  | `moderation_flagged`                                | Change the input, and send it with a new key. Nothing was charged.                                  |
| `402`  | `insufficient_credits`, `api_key_spend_cap_reached` | Buy an add-on credit pack, or raise the key's cap. Don't retry until you have.                      |
| `403`  | `insufficient_scope`                                | Use a key with `generation:write` and `avatars:write`.                                              |
| `409`  | `request_in_progress`                               | Still running. Wait `Retry-After` seconds and send the same request with the same key.              |
| `429`  | `rate_limited`                                      | Too many calls running or in the last minute. Wait `Retry-After`, then retry with the same key.     |
| `502`  | `provider_failed`                                   | Nothing usable came back, and nothing was charged. Retrying with the same key is safe.              |
| `503`  | `generation_unavailable`                            | Generation isn't offered here.                                                                      |

- [From an agent or the terminal](/docs/v2/agents/mcp-server): The MCP server's generation tools and `atmee generate` do the same, and the create-avatar skill asks before every paid call.