Generate portraits
Generates two square portraits of an invented character from a text
description, one from Gemini and one from Grok. Never use it to depict a real person: for a real
person, enhance their own photo with POST /v1/generation/enhancements,
with their permission.
- Output: each portrait is an
upload:<uploadId>thatPOST /v1/avatars(assets.image) andPUT /v1/avatars/{avatarId}/appearancetake as is (it expires after 24 hours), with a short-livedurland a small JPEGpreview. - Count:
countis 1 or 2 (default 2). 2 makes a Gemini and a Grok portrait, in that order; 1 makes the Gemini portrait only. A new call with a larger count is400 invalid_input. - Billing: one flat price per call, whatever the count (
GET /v1/account,pricing.generation.portraitsMicrocredits), charged when at least one portrait comes back: if one provider fails, the other's portrait costs the full price. The plan's free generation allowance pays first. A flagged, failed or refused call costs nothing. - Idempotency:
Idempotency-Keyis required. A retry with the same key never charges twice and returns the first result (replayed: true). - Scopes:
generation:writeandavatars:write.
X-Api-Key<token>Your secret API key (sk_atmee_...; older keys start sk_live_),
sent as X-Api-Key. Keep it on your server and never send it to a
browser.
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""v2hd""v2pro"count?integerHow many portraits to make, 1 or 2 (default 2). 2 is a Gemini and a Grok portrait, 1 the Gemini portrait only; the price is the same. A new call with 3 or 4 is refused as invalid_input (the schema allows them so a retry of a call made when four were allowed still returns its result).
1 <= value <= 4The portraits (or the replayed first result).
application/json- response
portraits*array<>1 <= items <= 4microcreditsCharged*integerWhat this call charged to credits (100 microcredits = 1 credit), after the plan's free generation allowance; 0 on a replay. The call's price is microcreditsCharged + microcreditsFree.
microcreditsFree*integerThe part of the price the plan's free generation allowance covered (pricing.generation.freeAllowance on GET /v1/account); 0 on a replay and when none is left.
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, "microcreditsFree": 0, "replayed": true, "failedProviders": [ "string" ]}
