POST
/
v1
/
teams
/
{teamId}
/
personas
/
{personaId}
/
render
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.personas.renderPersonaView({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  personaId: process.env.OCTOSPARK_PERSONA_ID ?? "personaId",
  body: {},
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "modelId": "<string>",
  "statusError": "<string>",
  "primaryAssetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "assetIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "estimatedCostDecimillicents": 123,
  "actualCostDecimillicents": 123,
  "callerIdempotencyKey": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

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