Generate portraits from a description
Generates up to four square portraits from a text description, one from
each configured image provider, with Atmee Studio's portrait prompt. For
an invented character only: never use it to depict a real person from a
description. For a real person, enhance their own photo with
POST /v1/generation/enhancements, with their permission.
Each portrait is returned as upload:<uploadId>, which POST /v1/avatars
(assets.image) and the JSON form of PUT /v1/avatars/{avatarId}/appearance
take as they are (an upload works once and expires 24 hours after it was
made), plus a short-lived url to view it and a small JPEG preview.
Costs the operation's price (GET /v1/account), charged only when at least
one portrait comes back; a flagged, failed or refused call costs nothing.
The Idempotency-Key is required: a retry with the same key never charges
twice and returns the first result (replayed: true). Requires
generation:write and avatars:write.
X-Api-Key<token>Secret embed API key (sk_atmee_...; keys minted before 2026-09
carry sk_live_...), held by the customer's own backend and never
sent to a browser. Format: X-Api-Key: sk_atmee_....
Idempotency-Key*stringA new UUID minted for this request. Reuse it only to retry the same request: a retry never charges twice and returns the first result. A malformed key, or a key already used with different inputs, gets 400 invalid_input.
length <= 255application/json- body
description*stringWhat the portrait shows (an invented character).
1 <= length <= 2000engine?stringThe avatar engine the portrait is for. v1 (the default) frames it from the shoulders up, facing the camera; v2 frames it half-body (waist up, hands visible) unless the description sets another framing, and keeps the pose and setting it asks for. Pass the engine the avatar will be created with.
"v1""v2"The portraits (or the replayed first result).
application/json- response
portraits*array<>1 <= items <= 4microcreditsCharged*integerWhat this call charged (100 microcredits = 1 credit); 0 on a replay.
replayed*booleanTrue when an earlier call with the same Idempotency-Key was replayed.
failedProviders*array<string>The providers that returned nothing usable.
curl -X POST 'https://api.atmanity.us/v1/generation/portraits' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "description": "string"}'{ "portraits": [ { "upload": "upload:3f1c2a9e-8d4b-4f6a-9c2e-1b7d5a0e4c11", "url": "http://example.com", "expiresAt": "2019-08-24T14:15:22Z", "preview": "string", "provider": "string", "unavailable": true } ], "microcreditsCharged": 0, "replayed": true, "failedProviders": [ "string" ]}