Atmee.aiDocs
APIAPI referenceGeneration

Generate portraits

POST
/v1/generation/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> that POST /v1/avatars (assets.image) and PUT /v1/avatars/{avatarId}/appearance take as is (it expires after 24 hours), with a short-lived url and a small JPEG preview.
  • Count: count is 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 is 400 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-Key is required. A retry with the same key never charges twice and returns the first result (replayed: true).
  • Scopes: generation:write and avatars:write.

Authorization

headerX-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.

Header Parameters

Idempotency-Key*string

A 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.

Lengthlength <= 255

Request Body

application/json
  1. body
description*string

What the portrait shows (an invented character).

Length1 <= length <= 2000
engine?string

The 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.

Value in"v1""v2""v2hd""v2pro"
count?integer

How 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).

Range1 <= value <= 4

Response Body

The portraits (or the replayed first result).

application/json
  1. response
portraits*array<>
Items1 <= items <= 4
microcreditsCharged*integer

What 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*integer

The 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*boolean

True when an earlier call with the same Idempotency-Key was replayed.

failedProviders*array<string>

The providers that returned nothing usable.

Example Request
curl -X POST 'https://api.atmanity.us/v1/generation/portraits' \  -H 'Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "description": "string"}'
Example Response
{  "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"  ]}