> ## 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 digital sample > Create a new digital sample in draft mode or actively initialized with a seed video. ## OpenAPI ````yaml /openapi.yaml post /digital-samples 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: /digital-samples: post: tags: - Digital Samples summary: Create digital sample description: >- Create a new digital sample in draft mode or actively initialized with a seed video. requestBody: required: true content: application/json: schema: type: object properties: title: type: string maxLength: 120 description: >- Optional custom title. If omitted, defaults to "API Sample ". (Max 120 characters) description: type: string maxLength: 300 nullable: true description: Optional description of the sample. (Max 300 characters) seedVideoUrl: type: string format: uri description: >- Optional public HTTPS URL to initialize the sample. YPH securely copies the file to R2, validates format and duration (≤170s), and automatically activates the sample. Echoed in responses; use `signedSeedVideoUrl` to preview the ingested copy. seedVideoDurationSec: type: integer maximum: 170 nullable: true description: Optional duration in seconds. Must be 170 seconds or less. positiveRenderPrompt: type: string maxLength: 2000 description: >- Optional custom positive render prompt for the Wan model. Defaults to standard actor-replacement prompt. (Max 2000 characters) negativeRenderPrompt: type: string maxLength: 2000 description: >- Optional custom negative render prompt for the Wan model. Defaults to standard actor-replacement negative prompt. (Max 2000 characters) renderSeedFps: type: integer enum: - 16 - 24 - 30 default: 16 description: >- Optional seed FPS tier (16 Economy, 24 Balanced, 30 Premium Quality). renderVoiceConversionEnabled: type: boolean default: true description: Optional flag to enable CosyVoice actor voice replacement. renderEntryWidth: type: integer enum: - 480 - 720 default: 480 description: >- Optional portrait 9:16 analysis size (480 Economy, 720 Balanced). accountToken: type: string maxLength: 128 nullable: true description: >- Opaque integrator **brand** id for this sample (scoped to your org). productToken: type: string maxLength: 128 nullable: true description: >- Optional integrator catalog **product** id (distinct from public `productUrl` listing link used in Collab flows). responses: '201': description: Created successfully content: application/json: schema: type: object properties: digitalSample: $ref: '#/components/schemas/DigitalSample' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: DigitalSample: type: object description: > Digital sample resource returned by GET, POST, and PATCH. - **Write-only (POST/PATCH body):** `seedVideoUrl` — your public HTTPS source URL. YPH ingests a copy into private storage. Use the presigned upload flow (`/seed/upload-url` + `/seed/register`) when uploading directly. - **Read-only (responses):** `signedSeedVideoUrl` — short-lived presigned GET URL for preview/download. Never send this back on PATCH. - **Echo (responses):** `seedVideoUrl` repeats the external source URL you submitted (null when the seed was uploaded via presigned PUT or created in the YPH app). - **Integrator identity:** `accountToken` identifies the **brand** (your marketplace advertiser). `productToken` is your internal catalog product id. See [Integrator tokens](/guides/integrator-tokens). - **Credits:** Org credit balance is not on this resource — use `GET /account` (`creditBalance`). properties: id: type: string format: uuid orgId: type: string nullable: true title: type: string description: type: string nullable: true positiveRenderPrompt: type: string nullable: true negativeRenderPrompt: type: string nullable: true renderSeedFps: type: integer renderVoiceConversionEnabled: type: boolean renderEntryWidth: type: integer seedVideoUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external seed video HTTPS URL (write via POST/PATCH body only). Null when the seed was uploaded via presigned PUT or the YPH app. signedSeedVideoUrl: type: string format: uri nullable: true readOnly: true description: >- Short-lived presigned GET URL for the ingested seed video (typically valid ~15 minutes). seedAssetPending: type: boolean seedVideoDurationSec: type: integer nullable: true status: type: string enum: - DRAFT - ACTIVE - ARCHIVED videoReviewStatus: type: string nullable: true enum: - IN_REVIEW - CHANGES_REQUESTED - APPROVED accountToken: type: string nullable: true maxLength: 128 description: Integrator brand id (opaque, scoped to your org). productToken: type: string nullable: true maxLength: 128 description: Integrator catalog product id (optional). renderMetadataStatus: type: string nullable: true enum: - pending - running - ready - failed readOnly: true description: >- Variation-scoped render-metadata readiness for actor-swap renders, surfaced when the read resolves the active/selected variation. Internal mask/pose bundle keys are never exposed. Omitted when not applicable. createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: d3b07384-d113-4956-a5e2-416b2a41bc3c orgId: org_123abc title: Summer Vacation description: Outdoor digital sample for summer looks positiveRenderPrompt: cinematic sunset, detailed face, 8k negativeRenderPrompt: blurry, low quality, bad hands renderSeedFps: 30 renderVoiceConversionEnabled: true renderEntryWidth: 720 seedVideoUrl: https://cdn.example.com/seeds/summer.mp4 signedSeedVideoUrl: >- https://account.r2.cloudflarestorage.com/bucket/seed-assets/sample.mp4?X-Amz-Signature=... seedAssetPending: false seedVideoDurationSec: 15 status: ACTIVE videoReviewStatus: APPROVED accountToken: brand_nike productToken: sku_air_max_90 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: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingTitle: summary: Missing Required Title value: code: REQUIRED_FIELD_MISSING error: title is required parameter: title invalidFps: summary: Invalid FPS Value value: code: INVALID_PARAMETER error: renderSeedFps must be 16, 24, or 30 parameter: renderSeedFps invalidWidth: summary: Invalid Entry Width value: code: INVALID_PARAMETER error: renderEntryWidth must be 480 or 720 parameter: renderEntryWidth durationExceeded: summary: Seed Video Too Long value: code: INVALID_PARAMETER error: video duration exceeds maximum allowed 170 seconds parameter: seedVideoUrl 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_… ````