Concepts and voices

← UGC videos 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:

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.

Choose a recipe

curl https://makelocalads.com/api/v1/video-recipes \
  --header "Authorization: Bearer $LOCALADS_API_KEY"

{
  "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:

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:

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"

{
  "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:

curl "https://makelocalads.com/api/v1/voices?product_id=a1516a75-9be5-461a-93af-c1896a0a3127&gender=female" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"

{
  "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 for the error format.

Get started

Set up

Ad campaigns

Listing images

Photoshoots

ChatGPT ads

UGC videos

Core concepts

Help

Choose an audience

Choose a recipe

Generate and pick a concept

Pick a voice

Errors

​Choose an audience

​Choose a recipe

​Generate and pick a concept

​Pick a voice

​Errors

Choose an audience

Choose a recipe

Generate and pick a concept

Pick a voice

Errors