POST
TypeScript client

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key
string

Reuse this key and the original body after a lost response. Changed requests return 409. For generated creation, this header must match the payload idempotencyKey.

Required string length: 1 - 512

Path Parameters

teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

personaId
string
required

Persona id (UUID), returned by list or create persona.

Body

application/json
prompt
string
required

a string at most 10000 character(s) long

Required string length: 1 - 10000
cameraView
enum<string>
required

The requested camera angle for the new persona image: front, three-quarter, profile, or back.

Available options:
front,
three_quarter,
profile,
back
framing
enum<string>
required

The requested composition for the new persona image, such as a headshot or full-body view.

Available options:
headshot,
portrait,
half_body,
full_body
identityShot
enum<string>

The identity-pack view to generate. Omit this to render a standalone persona image without filling a pack view.

Available options:
character_sheet,
front_neutral,
three_quarter_left,
three_quarter_right,
profile_left,
profile_right,
front_smile,
front_talking,
full_body_back,
waist_up_hands,
full_body_front,
full_body_three_quarter
draftProfile
object

An unsaved complete persona profile used only to render a preview. It is captured in the generation snapshot and is not persisted by this request.

portrayedAge
integer

a number between 15 and 75

Required range: 15 <= x <= 75
lifeEventIds
string<uuid>[]

an array of at most 100 item(s)

Maximum array length: 100

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
modelId
string

Persona image requests use google/gemini-3.1-pro-image. Omit modelId or provide that value. New requests for another model are rejected before setup or generation; matching accepted requests retain their original replay behaviour.

Required string length: 1 - 512
seed
integer

an integer

Response

Success

id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
organizationId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
sourceSurface
enum<string>
required
Available options:
studio,
agent,
editor,
persona
modelId
string
required
modality
enum<string>
required
Available options:
image,
video
route
enum<string>
required
Available options:
openrouter,
fal
status
enum<string>
required
Available options:
queued,
reserved,
running,
rate_limited,
ready,
failed,
cancelled,
skipped_insufficient_credits
statusError
string | null
required
primaryAssetId
string<uuid> | null
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
assetIds
string<uuid>[]
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
estimatedCostDecimillicents
number
required
actualCostDecimillicents
number
required
callerIdempotencyKey
string | null
required
createdAt
string
required
updatedAt
string
required