> ## 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.

# Enterprise API installation & asset quality (beta)

> Onboarding checklist, integration steps, and current asset constraints for best render quality.

<Warning>
  **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](/api-reference/health) when you upgrade integrations.
</Warning>

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

## 1. Request access & install credentials

<Steps>
  <Step title="Request API activation">
    API access is **off by default**. Email [michel@yourproducthere.ai](mailto:michel@yourproducthere.ai?subject=Enterprise%20API%20activation%20-%20YPH%20AI) with your org name and integration use case.
  </Step>

  <Step title="Generate an API key">
    Sign in at [yourproducthere.ai](https://yourproducthere.ai), open [**Developer**](https://yourproducthere.ai/app/developer), and regenerate your key (`yph_sk_live_…`). Store it in a secrets manager — the full secret is shown **once**.
  </Step>

  <Step title="Confirm base URL & docs">
    Production base: `https://api.yourproducthere.ai/v1`. Keep this site ([docs.yourproducthere.ai](https://docs.yourproducthere.ai)) and [`llms.txt`](/llms.txt) in your repo for AI-assisted integration.
  </Step>

  <Step title="Smoke test">
    ```bash theme={null}
    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`.
  </Step>
</Steps>

Partner diligence: [Company credentials](https://yourproducthere.ai/credentials) · [Enterprise use case](https://yourproducthere.ai/use-cases/enterprise-b2b-api)

## 2. Integration order (canonical)

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

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

See [Integrator tokens](/guides/integrator-tokens) for brand vs creator scoping and `isBrandSelfService`.

Details: [End-to-end workflow](/guides/workflow) · [Integrator tokens](/guides/integrator-tokens) · [Authentication](/authentication) · [Webhooks](/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`                                          |

<Note>
  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.
</Note>

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

<Info>
  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.
</Info>

## 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`](/llms.txt) — skills context with bounds and workflow order
* [OpenAPI reference](/api-reference/health) — schemas and examples
* This page — **human-readable beta constraints**

## 9. Versioning

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

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

Questions or activation: [michel@yourproducthere.ai](mailto:michel@yourproducthere.ai)