Skip to main content
PATCH
Update actor

Authorizations

Authorization
string
header
required

Your organization API key starting with yph_sk_live_…

Path Parameters

id
string<uuid>
required

Body

application/json
displayName
string

Optional updated display name for the actor.

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

Optional updated secure face image URL (passing null clears the current face). If a new URL is provided, it is securely ingested and hosted.

bodyAssetUrl
string<uri> | null

Optional updated secure body asset URL (passing null clears the current body). If a new URL is provided, it is securely ingested and hosted.

voiceClipUrl
string<uri> | null

Optional updated secure voice clip URL (passing null clears the current voice clip). If a new URL is provided, it is securely ingested and hosted. Must be MP3, WAV, or OGG clean speech between 10-30 seconds.

accountToken
string | null

Optional updated integrator actor token (pass null to clear).

Maximum string length: 128

Response

Updated 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>