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 | A description of an invented character | Up to two portraits | Portraits and enhancement |
POST /v1/generation/enhancements | A photo, and optionally how to restyle it | Up to two portraits of the same person | Portraits and enhancement |
POST /v1/generation/voices | A description of how the voice should sound | Voice previews of 10 to 60 seconds | Voice design |
POST /v1/generation/clips | An image and a prompt, audio optional | An mp4 of up to 15 seconds | Video generation |
Portraits, enhancements and voices make what an avatar is built from; pass the result straight to Create an avatar. A clip needs no avatar at all.
What each call costs
| Call | Price |
|---|---|
| Portraits | 1 credit per call, for one or two portraits (count, 2 if you leave it out) |
| Enhance or restyle | 1 credit per call, for up to two portraits |
| Voice design | 1 credit per call (two previews) |
| Video clips | 0.1 to 2 credits per clip, by length and size: see Sizes and cost |
A portrait or enhancement call costs its 1 credit when at least one image comes back: if one of the two image providers fails, you still pay the 1 credit for the other's image.
Free generation quota on paid plans. Each billing cycle, portraits, enhancements and voice
design first use your plan's free generation quota: 3 on Starter, 10 on Pro, 25 on Growth and 50
on Scale. A portrait, enhancement or voice design call uses 1 of it, the same as its price in
credits. Only what the quota doesn't cover is charged to your credits. Video clips always use
credits. Each answer's
microcreditsCharged is what came out of your credits, and microcreditsFree what the quota
covered.
What every call has in common
- A key with the right scopes:
generation:writefor video clips;generation:writeandavatars:writefor portraits, enhancement and voices, which are an avatar's inputs. Without them, the call answers403 insufficient_scope. See API keys. - An
Idempotency-Keyheader 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 withreplayed: 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-livedurlto 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
microcreditsChargedsays what came out of your credits andmicrocreditsFreewhat free generation covered, in hundredths of a credit (100is 1 credit).GET /v1/accountlists each call's price underpricing.generation, and what is left of your free generation underpricing.generation.freeAllowance. - Inputs are moderated first. Descriptions, prompts, sample text and photos are checked before
anything is made; a flagged input answers
moderation_flaggedand 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 (clips), plus avatars:write for portraits and voices. |
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. |
Create an avatar
Two ways to create an avatar with the API: send a JSON manifest that points at your files, or upload everything in one zip. Either builds Atmee V2 or Atmee V1.
Video generation
Turn an image and a prompt, with optional audio, into an mp4 of up to 15 seconds. No avatar, persona or live session needed.

