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

# Concepts and voices

> Pick the audience, recipe, concepts and voice before creating a UGC video.

[← UGC videos](/ugc-videos/overview)

**Endpoints:** `GET /products/{product_id}/audiences`, `GET /video-recipes`,
`POST /video-concepts`, `GET /video-concepts`, `GET /voices`
**Permissions:** `videos:read` to list, `videos:generate` for concepts

A UGC video is made from four choices. Three of them, everything except the
final render, are free.

## Choose an audience

Every product gets audiences automatically when it is created. List them and
pick one:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/audiences \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

Use its `id` as `audience_id` in the next steps, or `null` for a deliberately
broad video. Leaving `audience_id` out is an error, so an audience is never
skipped by accident. See [Audiences](/setup/audiences).

## Choose a recipe

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://makelocalads.com/api/v1/video-recipes \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "ugc-30s-voiceover",
      "title": "30s Authentic UGC Voiceover Ad",
      "subtitle": "UGC Voiceover Recipe",
      "duration_seconds": 30,
      "preview_video_url": "https://makelocalads.com/video-ads/blueprints/ugc-30s-voiceover-preview.mp4",
      "poster_url": "https://makelocalads.com/video-ads/blueprints/ugc-30s-voiceover-poster.jpg"
    }
  ]
}
```

## Generate and pick a concept

Start three concepts for the audience:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url https://makelocalads.com/api/v1/video-concepts \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "audience_id": "0f0c5a4e-54f7-4f0e-9d4e-1a8c3a6b5d11"
  }'
```

Concepts are kept per audience. If this audience already has concepts, you get
them back instead of new ones; send `"force": true` to replace them.

Poll until three concepts have titles:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://makelocalads.com/api/v1/video-concepts?product_id=a1516a75-9be5-461a-93af-c1896a0a3127&audience_id=0f0c5a4e-54f7-4f0e-9d4e-1a8c3a6b5d11" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "5b7e0f7a-6a55-4f0b-9f6c-8f0a2c1d3e4f",
      "status": "completed",
      "title": "The 6 a.m. calm",
      "description": "A parent shows how the throw turns a chaotic morning into a quiet one.",
      "image_url": "https://cdn.example.com/concepts/calm.png",
      "creator_gender": "female"
    }
  ]
}
```

A concept can be picked as soon as it has a title; its image is a preview.
Each concept carries its own hook, setting and creator.

## Pick a voice

Voices default to the accent of the market your brand sells in. Filter by the
concept's creator so the narrator matches:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://makelocalads.com/api/v1/voices?product_id=a1516a75-9be5-461a-93af-c1896a0a3127&gender=female" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "locale": "en-US",
  "market_country": "US",
  "data": [
    {
      "id": "9c3b7a1e-2d4f-4e6a-8b0c-1d2e3f4a5b6c",
      "name": "Maya",
      "tagline": "Warm and conversational",
      "gender": "feminine",
      "accent": "American",
      "locale": "en-US",
      "preview_url": "https://makelocalads.com/api/video-ads/voice-preview/9c3b7a1e-2d4f-4e6a-8b0c-1d2e3f4a5b6c?v=2"
    }
  ]
}
```

Pass `locale` (for example `en-GB` or `hi-IN`) for another accent.
`preview_url` plays a short demo and needs no key.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_request` | `audience_id` is missing from a concepts request (send an audience or `null`) |
| `404` | `product_not_found`, `audience_not_found` | Not available to you |

See [Errors and retries](/concepts/errors) for the error format.