Skip to main content
POST
Create actor

Authorizations

Authorization
string
header
required

Your organization API key starting with yph_sk_live_…

Body

application/json
displayName
string
required

The display/stage name for the actor. (Max 80 characters, required)

Maximum string length: 80
faceAssetUrl
string<uri> | null

Optional secure HTTP/HTTPS URL to the actor's face image (PNG/JPEG). This image will be securely ingested and hosted in our private storage. Note that the original image should ideally be high-quality and cropped/sized exactly to 480x832 pixels.

bodyAssetUrl
string<uri> | null

Optional secure HTTP/HTTPS URL to the actor's body image or reference (PNG/JPEG). This image will be securely ingested and hosted in our private storage. Note that the original image should ideally be high-quality and cropped/sized exactly to 480x832 pixels.

voiceClipUrl
string<uri> | null

Optional secure HTTP/HTTPS URL to a short reference voice audio clip (MP3, WAV, or OGG). This audio will be securely ingested and hosted in our private storage. Note that the voice clip must be at least 10 seconds (and at most 30 seconds) of clean speech.

accountToken
string | null

Opaque integrator id for this actor (creator or brand-owned identity). Scoped to your org. Used by embed widgets to list only that participant's actors. See Integrator tokens.

Maximum string length: 128

Response

Created successfully

Actor resource returned by GET, POST, and PATCH.

  • Write-only (POST/PATCH body): faceAssetUrl, bodyAssetUrl, voiceClipUrl — your public HTTPS source URLs. YPH ingests copies into private storage.
  • Read-only (responses): signedFaceAssetUrl, signedBodyAssetUrl, signedVoiceClipUrl — short-lived presigned GET URLs for preview/download. Never send these back on PATCH.
  • Echo (responses): faceAssetUrl, bodyAssetUrl, voiceClipUrl repeat the external source URLs you submitted (null if the actor was created via the YPH app upload flow).
  • Integrator identity: accountToken identifies the creator (or the brand when producing in-house). See Integrator tokens.
id
string<uuid>
displayName
string
Maximum string length: 80
accountToken
string | null

Integrator creator or brand actor id.

Maximum string length: 128
faceAssetUrl
string<uri> | null
read-only

Echo of your external face image HTTPS URL (write via POST/PATCH body only). Null when no external source was registered.

bodyAssetUrl
string<uri> | null
read-only

Echo of your external body image HTTPS URL (write via POST/PATCH body only).

voiceClipUrl
string<uri> | null
read-only

Echo of your external voice clip HTTPS URL (write via POST/PATCH body only).

signedFaceAssetUrl
string<uri> | null
read-only

Short-lived presigned GET URL for the ingested face asset (typically valid ~10 minutes).

signedBodyAssetUrl
string<uri> | null
read-only

Short-lived presigned GET URL for the ingested body asset.

signedVoiceClipUrl
string<uri> | null
read-only

Short-lived presigned GET URL for the ingested voice clip.

identityPrepStatus
enum<string>
read-only

Whether the actor has completed first-render AI identity prep (automatic photo optimization). pending until the first paid render prepares the assets, then preparingready. failed is non-blocking — renders still succeed with defaults. Poll this field after a PATCH that changes faceAssetUrl/bodyAssetUrl (which resets it to pending).

Available options:
pending,
preparing,
ready,
failed
identityPrepReadyAt
string<date-time> | null
read-only

Timestamp when identity prep last succeeded, or null if never prepared.

warnings
string[]
read-only

Non-blocking quality hints from asset validation (e.g. recommended dimensions or audio duration).

createdAt
string<date-time>
updatedAt
string<date-time>