Create actor
Create a new custom actor with a display name and optional URLs for face, body, or voice clip assets.
Authorizations
Your organization API key starting with yph_sk_live_…
Body
The display/stage name for the actor. (Max 80 characters, required)
80Optional 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.
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.
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.
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.
128Response
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,voiceClipUrlrepeat the external source URLs you submitted (null if the actor was created via the YPH app upload flow). - Integrator identity:
accountTokenidentifies the creator (or the brand when producing in-house). See Integrator tokens.
80Integrator creator or brand actor id.
128Echo of your external face image HTTPS URL (write via POST/PATCH body only). Null when no external source was registered.
Echo of your external body image HTTPS URL (write via POST/PATCH body only).
Echo of your external voice clip HTTPS URL (write via POST/PATCH body only).
Short-lived presigned GET URL for the ingested face asset (typically valid ~10 minutes).
Short-lived presigned GET URL for the ingested body asset.
Short-lived presigned GET URL for the ingested voice clip.
Whether the actor has completed first-render AI identity prep (automatic photo optimization). pending until the first paid render prepares the assets, then preparing → ready. failed is non-blocking — renders still succeed with defaults. Poll this field after a PATCH that changes faceAssetUrl/bodyAssetUrl (which resets it to pending).
pending, preparing, ready, failed Timestamp when identity prep last succeeded, or null if never prepared.
Non-blocking quality hints from asset validation (e.g. recommended dimensions or audio duration).
