> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas and Clips

> Create recurring AI creators with a locked identity, generate talking clips, review them and schedule the ones you approve.

A **persona** is an AI creator who posts for your app again and again: same face, same voice, same way of filming themselves. A **clip** is one short video of that persona saying a line in a scene.

> [!NOTE]
>
> UGC is in beta and needs access on your account. Generation spends [media credits](https://docs.appeeky.com/docs/ugc-overview.md#media-credits).

***

## Create a persona

In the dashboard: **UGC → Creators → New creator**.

* **From the creator library.** Pick one of 12 ready-made creators (wellness coach, remote developer, college student, busy mom, finance guy, startup founder, gamer, retiree, runner dad, beauty creator, traveler, home cook). It becomes your own persona, and you can change anything. The preview image is only a sample: you generate your own looks, so two apps never share one face.
* **From scratch.** Choose **Describe your own creator** and fill in who they are, their personality, appearance and voice.

### The creator lock

The creator lock holds everything that must stay the same from one generation to the next. Every photo and clip prompt carries it word for word.

| Section | Fields |
| - | - |
| **Identity** | Age, face, eyes, brows, skin, hair, build |
| **Signature details** | Small details that always show, like a ring or chipped nail polish |
| **Imperfections** | Flaws that repeat, so the creator looks real |
| **Camera habits** | Device, lens, distance, height, processing. Default: front-facing phone camera at arm's length, no beauty filter |
| **Voice profile** | Tone, verbal habits, accent |
| **Never change** | A list of things the model must never alter. Default: face, hair, signature details, skin texture |
| **Lane and formats** | The niche the creator owns and the formats they post in |

### Voices

Each persona can have a preset **speaking voice**, used for voiceovers and voiced talking clips in [Studio](https://docs.appeeky.com/docs/ugc-studio.md). There are 20 preset voices; `GET /v1/ugc/voices` lists them. Quick clips on the Creators tab use the video model's own voice.

***

## Pick a look

A persona needs a look before it can make clips.

1. Open the persona and click **Generate looks**. You get 4 candidate photos in about a minute (\~6 credits each).
2. Select 1–3 photos that show the same face.
3. Click **Use as look**. The persona becomes **active**, and every clip is generated from these photos.

Click **More looks** to get new candidates. Once a look is pinned, new candidates are variations of it.

***

## Generate a clip

On the persona's page, fill in:

| Field | Notes |
| - | - |
| **What they say** | One short spoken line, up to 280 characters (about 8 seconds) |
| **Scene** | Where they are and what they're doing, e.g. "sitting on the gym floor after a workout" |
| **Caption** | Post caption, used when you schedule the clip |
| **Model** | Only video models that make their own audio are offered, since the persona speaks the line |
| **Length** | The lengths the model supports. Default 8 s |

The price shows next to **Generate clip** before you start. A default clip (Veo 3.1 Fast, 8 s) costs about 186 credits.

Appeeky first renders a photo of the persona in your scene from their look, then animates it into a talking video. With a reference model such as **Veo 3.1 Reference**, the video is made straight from the look photos instead.

### Clip statuses

| Status | Meaning |
| - | - |
| **Generating** | Rendering |
| **Ready for review** | Rendered and waiting for you |
| **Approved** | Can be scheduled |
| **Rejected** | Won't be posted |
| **Scheduled** / **Posted** | Turned into a social post |
| **Failed** | Rendering failed. Held credits are refunded |

***

## Review and approve

Clips from the Creators tab, from [Studio](https://docs.appeeky.com/docs/ugc-studio.md) and from the Co-founder all wait for review. **Approve** opens a checklist:

* Face, hair and signature details match the creator
* Hands look right: five fingers, nothing melting
* The app screen or product label is readable and doesn't change
* The app isn't in the first 3 seconds or the last thing on screen
* AI-generated disclosure will be turned on when posting

Your answers are saved with the approval. **Reject** keeps the clip out of posting.

### Regenerate

For clips made in Studio, **Regenerate this shot** re-runs only the talking clip behind it. The old clip is marked rejected, and the new one arrives as *Ready for review*. It costs the same as rendering that shot again.

***

## Schedule

Click **Schedule post** on an approved clip, pick one or more connected TikTok or Instagram accounts, and set a time. Leave the time empty to post now. Connect accounts first in **Growth → Social Media → Accounts**.

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/ugc/creator-templates` | Ready-made creators from the library |
| GET | `/v1/ugc/voices` | Preset voices and the default voice |
| GET | `/v1/ugc/personas` | Your personas (`?includeArchived=true` to include archived) |
| POST | `/v1/ugc/personas` | Create a persona |
| GET | `/v1/ugc/personas/:personaId` | Get a persona |
| PATCH | `/v1/ugc/personas/:personaId` | Update any persona field, or archive it with `status: "archived"` |
| POST | `/v1/ugc/personas/:personaId/looks` | Generate look candidates (`count` 1–4, default 4). Returns a media job |
| PUT | `/v1/ugc/personas/:personaId/references` | Pin the look: `{ "assetIds": [...] }`, 1–6 images from your Library |
| POST | `/v1/ugc/personas/:personaId/clips` | Generate a clip (202) |
| GET | `/v1/ugc/clips` | List clips (`?personaId=`, `?status=`, `?limit=`, max 200) |
| GET | `/v1/ugc/clips/:clipId` | Get a clip with its video URL |
| PATCH | `/v1/ugc/clips/:clipId` | Edit `title` / `caption`, or set `status` to `approved` or `rejected` |
| POST | `/v1/ugc/clips/:clipId/regenerate` | Re-run the Studio shot behind a clip (202) |
| GET | `/v1/ugc/review/checklist` | The approval checklist items |
| POST | `/v1/ugc/clips/:clipId/schedule` | Schedule or post an approved clip |

These endpoints use 0 API credits. Generation is paid in media credits. Look candidates show up in `GET /v1/media/jobs?personaId=`.

### Persona fields

| Field | Type | Description |
| - | - | - |
| `name` | string | Required, 1–60 characters |
| `appId` | string | Optional. Ties the persona to one of your apps |
| `bio`, `story`, `personality`, `appearance`, `voice` | string | Free text, up to 4,000 characters each |
| `voiceId` | string | A preset voice id from `/v1/ugc/voices` |
| `style` | object | `camera`, `setting`, `lighting`, `wardrobe` |
| `identity` | object | `ageAppearance`, `face`, `eyes`, `brows`, `skin`, `hair`, `bodyBuild` |
| `signatureDetails`, `imperfections`, `neverChange` | string\[] | Up to 12 items each |
| `cameraHabits` | object | `device`, `lens`, `distance`, `height`, `processing` |
| `voiceProfile` | object | `tone`, `verbalHabits` (string\[]), `accent` |
| `lane` | string | The creator's niche |
| `formats` | string\[] | Up to 8 |
| `contentPillars`, `platforms` | string\[] | Up to 12 and 8 |
| `status` | string | `draft`, `active` or `archived` |

### Generate a clip

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/ugc/personas/PERSONA_ID/clips \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Okay, I did not expect a habit app to actually make me consistent.",
    "scene": "sitting on the gym floor after a workout",
    "caption": "Week 3 and still going",
    "videoModelId": "veo-3.1-fast",
    "durationSec": 8
  }'
```

| Field | Type | Description |
| - | - | - |
| `script` | string | Required. What the persona says, up to 280 characters |
| `scene` | string | Optional. Up to 600 characters |
| `caption` | string | Optional. Up to 2,200 characters |
| `title` | string | Optional. Up to 120 characters |
| `pipeline` | string | `still_then_video` (default) or `reference_video` |
| `videoModelId` | string | A video model with audio. Default `veo-3.1-fast`, or `veo-3.1-reference` for `reference_video` |
| `durationSec` | number | Default `8`. Rounded up to a length the model supports |
| `aspectRatio` | string | `9:16` (default) or `16:9` |
| `dryRun` | boolean | Return `credits`, `available` and `affordable` without generating |

Response (`202`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "clip": {
      "id": "3b0c6f8e-1d52-4a8e-9f0b-7c2e5a1d9e44",
      "personaId": "PERSONA_ID",
      "status": "generating",
      "script": "Okay, I did not expect a habit app to actually make me consistent.",
      "videoModelId": "veo-3.1-fast",
      "durationSec": 8,
      "aspectRatio": "9:16",
      "videoUrl": null
    },
    "credits": 186
  }
}
```

Poll `GET /v1/ugc/clips/:clipId` until `status` is `ready` or `failed`. `videoUrl` and `stillUrl` are short-lived links. Keep the clip id and fetch a fresh URL when you need one.

### Approve a clip

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
PATCH /v1/ugc/clips/CLIP_ID
{
  "status": "approved",
  "checklist": { "identity": true, "hands": true, "label": true, "productTiming": true, "aiDisclosure": true }
}
```

Only a rendered clip (`ready`, `approved` or `rejected`) can change status.

### Schedule a clip

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/ugc/clips/CLIP_ID/schedule
{
  "accountIds": ["social-account-id"],
  "scheduledFor": "2026-11-05T17:00:00.000Z",
  "timezone": "Europe/Istanbul",
  "caption": "Week 3 and still going"
}
```

Omit `scheduledFor` to post now. Account ids come from `GET /v1/connect/social/accounts`.

### Errors

| Status | Code | When |
| - | - | - |
| 400 | `MISSING_SCRIPT`, `SCRIPT_TOO_LONG` | No script, or longer than 280 characters |
| 400 | `INVALID_MODEL` | The model is silent or doesn't fit the pipeline |
| 400 | `INVALID_REFERENCES` | Not 1–6 Library images when pinning a look |
| 402 | `INSUFFICIENT_CREDITS` | Not enough media credits or balance |
| 403 | | UGC isn't enabled on your account |
| 404 | `PERSONA_NOT_FOUND`, `CLIP_NOT_FOUND` | Wrong id |
| 409 | `PERSONA_NEEDS_LOOK` | Pin a look before making clips |
| 409 | `CLIP_NOT_APPROVED` | Approve the clip before scheduling it |
| 409 | `CLIP_NOT_FROM_STUDIO` | Only Studio clips can be regenerated |

***

## Tips

* Keep each line to one idea. Short shots drift less.
* Pin 1–3 looks that clearly show the same face from slightly different angles.
* Fill in signature details and imperfections. They make the creator recognizable and keep them from looking too polished.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.