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

# Media Generation

> Generate images and short videos for your app through the API, paid with media credits.

**Media Generation** is the API behind UGC. Send a prompt, and optionally reference photos or a first frame, and Appeeky renders images or short vertical videos with the model you pick. Results are saved to your Library in a **UGC** folder.

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

***

## How it works

```
POST /media/images or /media/videos  →  credits held  →  job renders  →  saved to your Library
                                                                     │
                                                    GET /media/jobs/:jobId  →  completed + urls
```

1. **Price it.** Send the request with `dryRun: true` to get the exact credit cost without generating.
2. **Start the job.** The API answers `202` with a `jobId`. Credits for the job are held.
3. **Poll.** `GET /v1/media/jobs/:jobId` until `status` is `completed` or `failed`.
4. **Settle.** A completed job is charged. A failed job refunds the held credits.

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/media/models` | Models you can pick, with lengths, resolutions and credit prices |
| GET | `/v1/media/credits` | Your media credit balance this month |
| POST | `/v1/media/images` | Generate 1–4 images (202) |
| POST | `/v1/media/videos` | Generate a video (202) |
| GET | `/v1/media/jobs` | Your recent jobs (`?limit=`, max 200; `?personaId=`) |
| GET | `/v1/media/jobs/:jobId` | Job status and output URLs |

These endpoints use 0 API credits.

### Generate a video

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/media/videos \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "veo-3.1-fast",
    "prompt": "A woman in her late 20s sits on a yoga mat, looks into her phone camera and smiles, handheld, natural morning light",
    "imageUrl": "https://example.com/first-frame.png",
    "durationSec": 6,
    "aspectRatio": "9:16",
    "audio": true
  }'
```

| Field | Type | Description |
| - | - | - |
| `modelId` | string | A video model from `/v1/media/models`. Default `veo-3.1-fast` |
| `prompt` | string | Required. Up to 4,000 characters |
| `imageUrl` | string | The first frame. Required for image-to-video models |
| `referenceImageUrls` | string\[] | 1–3 reference photos. Required for reference-to-video models (`veo-3.1-reference`) |
| `durationSec` | number | One of the model's lengths. Default: its longest |
| `resolution` | string | `480p`, `720p` or `1080p`, if the model offers it. Default: the model's default |
| `aspectRatio` | string | `9:16` (default) or `16:9` |
| `audio` | boolean | Generate speech and sound. Default `true` on models with audio; ignored on silent models |
| `negativePrompt` | string | What to avoid |
| `seed` | number | For repeatable results |
| `folderId` | string | Library folder for the output |
| `dryRun` | boolean | Return `credits` only, without generating |

Image URLs must be public `https` links.

Response (`202`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "jobId": "9d4e1b7a-2f3c-4a5e-8b6d-0c1f2e3a4b5c",
    "kind": "video",
    "modelId": "veo-3.1-fast",
    "status": "queued",
    "assetIds": [],
    "urls": [],
    "credits": 135,
    "error": null,
    "createdAt": "2026-11-01T10:00:00.000Z",
    "completedAt": null
  }
}
```

### Generate images

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/media/images
{
  "modelId": "nano-banana",
  "prompt": "The same woman holding her phone in a sunny kitchen, phone screen facing the camera",
  "imageUrls": ["https://example.com/look-1.png"],
  "count": 2,
  "aspectRatio": "9:16"
}
```

| Field | Type | Description |
| - | - | - |
| `modelId` | string | An image model from `/v1/media/models`. Always set it |
| `prompt` | string | Required |
| `imageUrls` | string\[] | Optional reference photos to keep a face or product consistent. Up to 6 (10 for Seedream 4.5) |
| `count` | number | 1–4. Default `1` |
| `aspectRatio` | string | `9:16` (default), `16:9`, `1:1` or `4:5` |
| `seed` | number | For repeatable results |
| `folderId` | string | Library folder for the output |
| `dryRun` | boolean | Return `credits` only, without generating |

### Jobs

`status` is one of `queued`, `submitted`, `processing`, `completed`, `failed` or `cancelled`. When it is `completed`, `assetIds` holds the Library items and `urls` holds download links.

> [!WARNING]
>
> Output `urls` expire after a few hours. Store the `assetIds` or the `jobId`, and fetch the job again for fresh links.

`credits` is the held amount while a job runs, and the charged amount once it completes.

### Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_MODEL` | Unknown model, or the wrong kind for the endpoint |
| 400 | `MISSING_PROMPT`, `PROMPT_TOO_LONG` | No prompt, or over 4,000 characters |
| 400 | `INVALID_DURATION`, `INVALID_RESOLUTION`, `INVALID_ASPECT_RATIO` | A value the model doesn't support |
| 400 | `MISSING_IMAGE`, `INVALID_REFERENCES`, `INVALID_URL` | Missing first frame, wrong number of references, or a URL that isn't public `https` |
| 400 | `INVALID_COUNT` | `count` outside 1–4 |
| 402 | `INSUFFICIENT_CREDITS` | Not enough media credits or balance |
| 403 | | UGC isn't enabled on your account |
| 404 | `JOB_NOT_FOUND` | Wrong job id |

***

## Models

`GET /v1/media/models` is the source of truth. Prices below are in credits during the beta and may change.

### Image models

| Model | `modelId` | Credits per image |
| - | - | - |
| Nano Banana | `nano-banana` | 6 |
| Nano Banana 2 | `nano-banana-2` | 12 |
| Nano Banana Pro | `nano-banana-pro` | 23 |
| Seedream 4.5 | `seedream-4.5` | 6 |

All image models work from a prompt alone or with reference photos, and make up to 4 images per request.

### Video models

Credits per second at the default resolution, silent / with audio. All are image-to-video (they need `imageUrl`) except Veo 3.1 Reference.

| Model | `modelId` | Lengths (s) | Resolutions (default) | Audio | Credits / s |
| - | - | - | - | - | - |
| Veo 3.1 Lite | `veo-3.1-lite` | 4, 6, 8 | 720p, 1080p (720p) | Yes | 5 / 8 |
| Veo 3.1 Fast | `veo-3.1-fast` | 4, 6, 8 | 720p, 1080p (720p) | Yes | 15 / 23 |
| Veo 3.1 | `veo-3.1` | 4, 6, 8 | 720p, 1080p (720p) | Yes | 30 / 60 |
| Veo 3.1 Reference | `veo-3.1-reference` | 8 | 720p, 1080p (720p) | Yes | 30 / 60 |
| Seedance 2.0 | `seedance-2.0` | 4–15 | 480p, 720p, 1080p (720p) | Yes | 46 |
| Seedance 2.0 Fast | `seedance-2.0-fast` | 4–15 | 480p, 720p (720p) | Yes | 37 |
| Seedance 2.0 Mini | `seedance-2.0-mini` | 4–15 | 480p, 720p (720p) | Yes | 24 |
| Seedance 2.5 | `seedance-2.5` | 4–30 | 480p, 720p, 1080p (720p) | Yes | 71 |
| Seedance 1.5 Pro | `seedance-1.5-pro` | 4–12 | 480p, 720p, 1080p (720p) | Yes | 4 / 8 |
| Seedance 1.0 Pro Fast | `seedance-1.0-pro-fast` | 2–12 | 480p, 720p, 1080p (720p) | No | 4 |
| Kling 3.0 Pro | `kling-v3-pro` | 3–15 | 1080p | Yes | 17 / 26 |
| Kling 3.0 Standard | `kling-v3-standard` | 3–15 | 720p | Yes | 13 / 19 |
| Kling 2.5 Turbo Pro | `kling-v2.5-turbo-pro` | 5, 10 | 1080p | No | 11 |
| Hailuo 2.3 | `hailuo-2.3` | 6, 10 | 720p | No | 9 |
| Wan 3.0 | `wan-3.0` | 2–15 | 480p, 720p, 1080p (720p) | Yes | 15 |
| LTX 2.3 Fast | `ltx-2.3-fast` | 6–20, even | 1080p | Yes | 9 |
| Sora 2 | `sora-2` | 4, 8, 12 | 720p | Yes | 15 |
| Sora 2 Pro | `sora-2-pro` | 4, 8, 12 | 720p, 1080p (720p) | Yes | 45 |

Higher resolutions cost more on some models. `byResolution` in `/v1/media/models` lists every rate. Per-second rates are rounded up, so `dryRun` gives the exact total. For example, 8 seconds of Veo 3.1 Fast with audio is 180 credits.

The models list also includes the talking-avatar and lip-sync models that [Studio](https://docs.appeeky.com/docs/ugc-studio.md#talking-clip-voices) uses to animate a photo to a voice track.

***

## Related

* [UGC Overview](https://docs.appeeky.com/docs/ugc-overview.md): credits, allowances and the dashboard
* [Personas and Clips](https://docs.appeeky.com/docs/ugc-personas-and-clips.md): consistent creators instead of one-off prompts
* [Studio](https://docs.appeeky.com/docs/ugc-studio.md): chain images and videos into one edit


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