> ## Documentation Index > Fetch the complete documentation index at: https://docs.yourproducthere.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create actor > Create a new custom actor with a display name and optional URLs for face, body, or voice clip assets. ## OpenAPI ````yaml /openapi.yaml post /actors openapi: 3.1.0 info: title: YPH Public API version: 1.0.0 description: | Programmatic access to Digital Samples, Actors, Insta Swaps, and webhooks. Authenticate with `Authorization: Bearer yph_sk_live_…`. servers: - url: https://api.yourproducthere.ai/v1 description: Production security: - bearerAuth: [] tags: - name: System - name: Account - name: Actors - name: Digital Samples - name: Insta Swaps - name: Webhooks paths: /actors: post: tags: - Actors summary: Create actor description: >- Create a new custom actor with a display name and optional URLs for face, body, or voice clip assets. requestBody: required: true content: application/json: schema: type: object required: - displayName properties: displayName: type: string maxLength: 80 description: >- The display/stage name for the actor. (Max 80 characters, required) faceAssetUrl: type: string format: uri nullable: true description: >- 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: type: string format: uri nullable: true description: >- 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: type: string format: uri nullable: true description: >- 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: type: string maxLength: 128 nullable: true description: > 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](/guides/integrator-tokens). responses: '201': description: Created successfully content: application/json: schema: $ref: '#/components/schemas/Actor' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingDisplayName: summary: Missing Display Name value: code: REQUIRED_FIELD_MISSING error: displayName is required parameter: displayName invalidFaceUrl: summary: Invalid Face Asset URL value: code: INVALID_PARAMETER error: faceAssetUrl must be a valid, secure HTTPS URL parameter: faceAssetUrl '401': $ref: '#/components/responses/Unauthorized' components: schemas: Actor: type: object description: > 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](/guides/integrator-tokens). properties: id: type: string format: uuid displayName: type: string maxLength: 80 accountToken: type: string nullable: true maxLength: 128 description: Integrator creator or brand actor id. faceAssetUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external face image HTTPS URL (write via POST/PATCH body only). Null when no external source was registered. bodyAssetUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external body image HTTPS URL (write via POST/PATCH body only). voiceClipUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external voice clip HTTPS URL (write via POST/PATCH body only). signedFaceAssetUrl: type: string format: uri nullable: true readOnly: true description: >- Short-lived presigned GET URL for the ingested face asset (typically valid ~10 minutes). signedBodyAssetUrl: type: string format: uri nullable: true readOnly: true description: Short-lived presigned GET URL for the ingested body asset. signedVoiceClipUrl: type: string format: uri nullable: true readOnly: true description: Short-lived presigned GET URL for the ingested voice clip. identityPrepStatus: type: string readOnly: true enum: - pending - preparing - ready - failed description: >- 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`). identityPrepReadyAt: type: string format: date-time nullable: true readOnly: true description: >- Timestamp when identity prep last succeeded, or null if never prepared. warnings: type: array readOnly: true items: type: string description: >- Non-blocking quality hints from asset validation (e.g. recommended dimensions or audio duration). createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: a1c02874-e339-4d11-8fa1-e6a2bc38c41d displayName: Corporate Professional accountToken: creator_42 faceAssetUrl: https://cdn.example.com/actors/face.jpg bodyAssetUrl: https://cdn.example.com/actors/body.jpg voiceClipUrl: https://cdn.example.com/actors/voice.mp3 signedFaceAssetUrl: >- https://account.r2.cloudflarestorage.com/bucket/identity-assets/face.png?X-Amz-Signature=... signedBodyAssetUrl: >- https://account.r2.cloudflarestorage.com/bucket/identity-assets/body.png?X-Amz-Signature=... signedVoiceClipUrl: >- https://account.r2.cloudflarestorage.com/bucket/identity-assets/voice.mp3?X-Amz-Signature=... identityPrepStatus: pending identityPrepReadyAt: null warnings: - 'faceAssetUrl: image dimensions below recommended 480x832' createdAt: '2026-06-20T12:00:00Z' updatedAt: '2026-06-20T12:05:00Z' Error: type: object properties: code: type: string description: >- A machine-readable, uppercase error code (e.g. `REQUIRED_FIELD_MISSING`, `INVALID_PARAMETER`, `RESOURCE_NOT_FOUND`, `UNAUTHORIZED`, `CONFLICT`). error: type: string description: A human-readable error message explaining why the request failed. parameter: type: string nullable: true description: >- The name of the specific input parameter or body field that caused the error (e.g. `seedVideoUrl`, `title`, etc.). details: type: object nullable: true description: >- Additional key-value pairs providing context or structured details about the failure. example: code: REQUIRED_FIELD_MISSING error: title is required parameter: title details: null responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: summary: Invalid API Key value: code: UNAUTHORIZED error: Unauthorized securitySchemes: bearerAuth: type: http scheme: bearer description: Your organization API key starting with yph_sk_live_… ````