Enterprise API installation & asset quality (beta)

Beta constraints — validation rules and quality recommendations on this page reflect the current Public API and render pipeline. We tighten and relax limits as the product matures. Check updatedAt on this page and the changelog in OpenAPI when you upgrade integrations.

This guide is for enterprise / platform integrators after API access is enabled. It complements the workflow guide with onboarding steps and asset preparation rules that match the YPH app upload UI and server validators today.

1. Request access & install credentials

Request API activation

API access is off by default. Email [email protected] with your org name and integration use case.

Generate an API key

Sign in at yourproducthere.ai, open Developer, and regenerate your key (yph_sk_live_…). Store it in a secrets manager — the full secret is shown once.

Confirm base URL & docs

Production base: https://api.yourproducthere.ai/v1. Keep this site (docs.yourproducthere.ai) and llms.txt in your repo for AI-assisted integration.

Smoke test

curl -s https://api.yourproducthere.ai/v1/health
curl -s https://api.yourproducthere.ai/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Expect apiAccessEnabled: true and a credit balance on /account.

Partner diligence: Company credentials · Enterprise use case

2. Integration order (canonical)

Follow this order on every environment — skipping steps causes 400/404/409 errors:

POST /digital-samples (draft or with external seedVideoUrl) — set accountToken (brand) and optional productToken for enterprise embeds
Seed video — presigned upload-url → PUT → register, or HTTPS ingest via seedVideoUrl
POST /actors (face + body + voice URLs) — set accountToken (creator or brand)
POST /digital-samples/{id}/insta-swaps (charges 1 credit on queue) — optional accountToken on swap (defaults from actor)
Poll GET /insta-swaps/{id} or register POST /webhooks for insta_swap.*

See Integrator tokens for brand vs creator scoping and isBrandSelfService. Details: End-to-end workflow · Integrator tokens · Authentication · Webhooks

3. Digital Sample seed video

Seed quality drives Insta Swap output. The API and app enforce the same hard limits; the app also shows soft warnings for best results.

Hard limits (API rejects or deletes object)

Rule	Value	Error / behavior
Container	MP4 or MOV (`video/mp4`, `video/quicktime`)	`seed_mp4_or_mov_required` / ingest failure
Duration	≤ 30 seconds	`video_too_long` / `video duration exceeds maximum allowed 30 seconds`
File size	≤ 80 MB (83,886,080 bytes)	Presign `400`; ingest deletes oversize object
`seedVideoDurationSec`	≤ 30 when sent in JSON	`400` validation
Aspect (strict UI)	9:16 vertical required in app wizard	App blocks continue if not vertical
Aspect (API ingest)	9:16 recommended	Non–9:16 may warn (`not_vertical_9_16`) on register; API path may still accept
Source URL	Public HTTPS (no localhost / private IPs)	Ingest `400`
Replace seed	Blocked if sample has active collaborations	`409 seed_replace_blocked_collaborations`

Workers cannot run ffprobe. Duration and aspect are parsed from ISO BMFF (moov/tkhd) when possible. If metadata is unreadable (e.g. moov at end of file), the API may accept the file with a dimensions_unparsed warning — re-export with “fast start” / web-optimized MP4 for reliable validation.

Safe-shot checklist (beta — from product UI)

For best likeness and fewer failed renders, seed content should:

Show only one person on camera
Avoid biting food, outfit changes, or applying products on camera
Match the SKU/listing you will attach in Collab flows
Avoid scripts that instruct affiliates to claim personal use (“I tried”, “my honest review”, etc.)
Include only media you own or have rights to (people, product, music)

Upload paths

Method	When to use
Presigned PUT (`/seed/upload-url` + PUT + `/seed/register`)	You control the file bytes; best for DAM/PIM pipelines
HTTPS `seedVideoUrl` on create/PATCH	YPH fetches and ingests from your CDN; must be publicly reachable

After ingest, use signedSeedVideoUrl in API responses to preview the private copy — never send signed URLs back on PATCH.

4. Actor assets (face, body, voice)

Provide HTTPS URLs on POST /actors or PATCH /actors/{id}. YPH ingests into private R2 and returns echo source URLs plus short-lived signed*AssetUrl fields.

Face & body images

Rule	Value
Formats	JPEG, PNG, WebP
Max size	Face 12 MB, body 15 MB
Recommended export	480 × 832 px, 9:16 portrait (matches render workflow)
Minimum source	At least 480 × 832 so we never upscale a tiny crop

OpenAPI and responses may include non-blocking warnings (e.g. dimensions below 480×832). Export exactly 480×832 from your asset pipeline for maximum quality.

Voice clip

Rule	Value
Formats	MP3, WAV, OGG
Max size	10 MB
Duration	10–30 seconds of clean speech
Content	Single speaker, minimal background noise

5. Render parameters (Digital Sample)

Set on create or PATCH. Invalid combinations return 400.

Field	Allowed values	Notes
`renderSeedFps`	16, 24, 30	Default 16. Higher FPS = better motion/lip sync, more GPU time
`renderEntryWidth`	480, 720	Portrait 9:16 analysis size; default 480
`renderVoiceConversionEnabled`	boolean	When `true`, replace seed audio with actor voice via CosyVoice

In the YPH app, 30 FPS with closest face match may be blocked on seeds longer than 25 seconds (hardware guardrail). Prefer 24 FPS or shorter seeds for premium tiers until this limit is lifted in a future release.

6. Insta Swap & webhooks

Each queued swap costs 1 credit (see GET /account).
Poll GET /insta-swaps/{id} until status is terminal, or use webhooks (insta_swap.queued, insta_swap.completed, insta_swap.failed).
Result video: signedResultVideoUrl (short-lived presigned GET).

7. Errors vs warnings

Type	Meaning	Action
HTTP 4xx + `error` / `parameter`	Hard validation failure	Fix input; object may be deleted from R2
`warnings[]` on Actor	Quality hint; request succeeded	Improve assets; re-upload optional
`warning` on seed register (app)	e.g. `not_vertical_9_16`, `dimensions_unparsed`	Re-export recommended; API may still proceed

8. AI-assisted development

Point Cursor, Claude, or Copilot at:

llms.txt — skills context with bounds and workflow order
OpenAPI reference — schemas and examples
This page — human-readable beta constraints

9. Versioning

We update this guide when validation or quality bars change. Integrators should:

Watch commits under mintlify/ in the monorepo
Re-run your staging conformance / Contract run after upgrades
Treat warnings as forward-compatible hints; treat new 4xx codes as breaking for automation

Questions or activation: [email protected]

Get started

Integrations

AI Integrators

Enterprise API installation & asset quality (beta)

1. Request access & install credentials

2. Integration order (canonical)

3. Digital Sample seed video

Hard limits (API rejects or deletes object)

Safe-shot checklist (beta — from product UI)

Upload paths

4. Actor assets (face, body, voice)

Face & body images

Voice clip

5. Render parameters (Digital Sample)

6. Insta Swap & webhooks

7. Errors vs warnings

8. AI-assisted development

9. Versioning

​1. Request access & install credentials

​2. Integration order (canonical)

​3. Digital Sample seed video

​Hard limits (API rejects or deletes object)

​Safe-shot checklist (beta — from product UI)

​Upload paths

​4. Actor assets (face, body, voice)

​Face & body images

​Voice clip

​5. Render parameters (Digital Sample)

​6. Insta Swap & webhooks

​7. Errors vs warnings

​8. AI-assisted development

​9. Versioning

1. Request access & install credentials

2. Integration order (canonical)

3. Digital Sample seed video

Hard limits (API rejects or deletes object)

Safe-shot checklist (beta — from product UI)

Upload paths

4. Actor assets (face, body, voice)

Face & body images

Voice clip

5. Render parameters (Digital Sample)

6. Insta Swap & webhooks

7. Errors vs warnings

8. AI-assisted development

9. Versioning