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

# UGC Studio

> Build multi-shot UGC videos on a canvas by connecting creators, photos, talking clips, voiceover, music and captions.

**Studio** is a canvas for UGC videos that need more than one shot. Each file is a flow of connected nodes: a creator, the photos and talking clips they appear in, a voiceover, music and captions, cut together into one video that goes to review.

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

***

## How it works

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  A[Creator] --> B[Photo]
  T[Script] --> C
  B --> C[Talking clip]
  C --> D[Final edit]
  V[Voiceover] --> D
  M[Music] --> D
  K[Captions] --> D
  D --> E[Send to review]
```

1. **Start a file** from a template, or from a blank canvas, in **UGC → Studio**. You can pre-pick a creator.
2. **Fill in the nodes.** Write the script, describe the scene, pick models and lengths.
3. **Run.** Select the nodes you want and run them. Nodes they depend on run first if they don't have a result yet. The price shows before you start.
4. **Review.** A **Send to review** node turns its video into a clip on the creator's page, where you approve it like any other clip. See [Personas and Clips](https://docs.appeeky.com/docs/ugc-personas-and-clips.md#review-and-approve).

Every result is saved to your Library under the creator's UGC folder.

***

## Templates

| Template | What it makes |
| - | - |
| **Blank** | An empty canvas |
| **Talking clip** | Creator → first frame in a scene → talking video with your script → review |
| **POV tutorial** | Reaction hook, the app step by step on the creator's phone, captions and an end card |
| **Testimonial + b-roll** | An opening line on camera, then narration over the app on their phone |
| **Problem → solution** | The creator names the problem, then their voice walks through the fix in the app |
| **3 reasons** | A spoken hook, then three numbered reasons, each on the app screen in the creator's hand |
| **Voiceover tutorial** | No talking head: the app on the creator's phone with their voice and word-by-word captions |
| **Before / after** | A frustrated "before" shot, an "after" with the app in hand, captions and music |
| **Day in the life** | Four moments of the creator's day, the app in one of them, with captions and music |
| **Reaction hook** | A silent reaction, a hook caption, the app on their phone and an end card. About 6 seconds |
| **Persona stills** | Consistent photos of the creator for slideshows and covers |

Each template shows its estimated credits in the gallery.

***

## Nodes

### Inputs

| Node | What it gives |
| - | - |
| **Creator** | A persona. Keeps their face, voice and creator lock in every shot it's connected to |
| **Text** | A **Script** (what is said), a **Scene** (where and what happens) or a **Prompt** |
| **Captions** | The hook, one line per shot and the call-to-action line for a Final edit |
| **Upload** | A photo, video or audio file from your Library |
| **App** | One of your App Store apps and a chosen screenshot. Its icon and name also go on the end card |

### Generators

| Node | What it makes | Cost |
| - | - | - |
| **Photo** | A still of the creator in a scene. The **Phone-in-hand** variant shows your app's screen on their phone | Per image, by model |
| **Talking clip** | The creator says the script in a short video, from a first frame. The **Reaction** variant has no words | Per second, by model and voice option |
| **Voiceover** | Narration in the creator's voice | 15 credits per 1,000 characters |
| **Music** | A background track from a prompt | Lyria 2: 15 credits per track. Stable Audio 2.5: 30 credits per track |
| **Final edit** | Shots in order, plus voiceover, music, captions and an end card, rendered as one MP4 | 10 credits |
| **Send to review** | Turns a video or photo into a clip waiting for your approval | Free |

### Talking clip voices

When a Talking clip has a script, the line is spoken in the creator's preset voice by default (or the node's voice when no creator is connected). The voice track is made first, then the first frame is animated to it:

| Option | Credits per second |
| - | - |
| **Kling Avatar** (default) | \~9 |
| **Kling Avatar Pro** | \~18, sharper face and motion |
| **OmniHuman 1.5** | \~24, most expressive body motion |
| **Video model + lip-sync** | The selected video model animates the shot silently, then the mouth is synced to the voice (\~8 per second for the sync) |

With a creator voice, a script can be up to 675 characters (about 45 seconds). You can also let the video model speak the line itself. Then the script is limited to 280 characters (about 8 seconds), and the model must make its own audio. A Talking clip is 6 seconds by default, a Reaction 4 seconds.

***

## Runs

* Only one run per file can be in progress at a time.
* The run is priced before it starts. If you don't have enough credits, it doesn't start.
* Each node shows its own status: queued, running, completed, failed or skipped. A failed node refunds its held credits.
* A file can hold up to 150 nodes and 400 connections.

***

## API

The canvas itself is edited in the dashboard. The API lets you list templates, create files from them, run them and read the results.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/ugc/studio/templates` | Templates with their steps and `estimatedCredits` |
| GET | `/v1/ugc/studio/files` | Your Studio files |
| POST | `/v1/ugc/studio/files` | Create a file (`name`, `templateId`, `personaId`; all optional) |
| GET | `/v1/ugc/studio/files/:fileId` | A file with its nodes and node results |
| PATCH | `/v1/ugc/studio/files/:fileId` | Rename it (`name`) or save the canvas (`graph`) |
| DELETE | `/v1/ugc/studio/files/:fileId` | Delete a file |
| POST | `/v1/ugc/studio/files/:fileId/runs` | Run nodes (202) |
| GET | `/v1/ugc/studio/files/:fileId/runs` | A file's runs (`?limit=`) |
| GET | `/v1/ugc/studio/runs/:runId` | Run status and node results |
| GET | `/v1/ugc/studio/apps` | Your App Store apps for the App node |
| GET | `/v1/ugc/studio/apps/:appId/screenshots` | An app's App Store screenshots (`?country=`, default `us`) |

These endpoints use 0 API credits. Runs are paid in media credits.

### Create a file and run it

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/ugc/studio/files \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "talking-clip", "personaId": "PERSONA_ID" }'
```

Without a `templateId`, the file starts blank. Then run the nodes you want by id:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/ugc/studio/files/FILE_ID/runs
{ "nodeIds": ["NODE_ID"], "dryRun": true }
```

With `dryRun: true`, you get the price and nothing runs:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "nodeIds": ["FRAME_NODE_ID", "NODE_ID"],
    "credits": 186,
    "available": 1312,
    "affordable": true
  }
}
```

`nodeIds` in the answer is the run order, including nodes the selection depends on. Send the same body without `dryRun` to start the run. Up to 50 nodes per request.

`GET /v1/ugc/studio/runs/:runId` returns the run's `status` (`queued`, `running`, `completed`, `failed` or `cancelled`) and a result per node with its `status`, `credits`, `error` and, for Send to review, the new `clipId`.

### Errors

| Status | Code | When |
| - | - | - |
| 400 | `STUDIO_INVALID` | Nothing to run, or a node is missing an input it needs |
| 400 | `STUDIO_CYCLE` | The connections form a loop |
| 400 | `STUDIO_TOO_LARGE` | Over 150 nodes or 400 connections |
| 402 | `INSUFFICIENT_CREDITS` | Not enough media credits or balance |
| 404 | `STUDIO_FILE_NOT_FOUND` | Wrong file id |
| 409 | `STUDIO_RUN_ACTIVE` | This file is already running |


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