Create a video ad

The API makes videos the way the app does. A UGC video follows the same four steps as the create-video dialog, and you make every choice the dialog lets you make:

Audience: who the video is for. Required: a saved audience, or null for a deliberately broad video.
Recipe: the video format. Today there is one, a 30 second UGC voiceover.
Concept: pick one of three concepts, each with its own hook, setting and creator.
Voice: pick the narrator.

You can also animate any finished Quick Shoot photo into a short video. A UGC video costs 2 credits per second: 60 credits for 30 seconds. An animation costs 2 credits per second of its length. Concepts, voices and recipes are free.

Before you start

You need:

an API key with videos:generate and videos:read
a product in LocalAds, on a plan that includes Video Ads
60 credits for a UGC video

1. 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 broad video. Leaving audience_id out is an error, so an audience is never skipped by accident. See Audiences.

2. 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"
    }
  ]
}

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

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

5. Create the video

curl --request POST \
  --url https://makelocalads.com/api/v1/videos \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: video-order-2201" \
  --data '{
    "type": "ugc",
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "recipe_id": "ugc-30s-voiceover",
    "audience_id": "0f0c5a4e-54f7-4f0e-9d4e-1a8c3a6b5d11",
    "concept_id": "5b7e0f7a-6a55-4f0b-9f6c-8f0a2c1d3e4f",
    "voice_id": "9c3b7a1e-2d4f-4e6a-8b0c-1d2e3f4a5b6c",
    "max_credits": 60
  }'

const response = await fetch("https://makelocalads.com/api/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOCALADS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "video-order-2201",
  },
  body: JSON.stringify({
    type: "ugc",
    product_id: "a1516a75-9be5-461a-93af-c1896a0a3127",
    recipe_id: "ugc-30s-voiceover",
    audience_id: "0f0c5a4e-54f7-4f0e-9d4e-1a8c3a6b5d11",
    concept_id: "5b7e0f7a-6a55-4f0b-9f6c-8f0a2c1d3e4f",
    voice_id: "9c3b7a1e-2d4f-4e6a-8b0c-1d2e3f4a5b6c",
    max_credits: 60,
  }),
});

const video = await response.json();

concept_id and voice_id are optional. Leave one out and the render chooses, the same as the app’s defaults. LocalAds returns 202 Accepted:

{
  "id": "e2d4c6a8-1b3f-4d5e-9a7c-0f1e2d3c4b5a",
  "type": "ugc",
  "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
  "status": "in_progress",
  "title": "The 6 a.m. calm",
  "recipe_id": "ugc-30s-voiceover",
  "audience_id": "0f0c5a4e-54f7-4f0e-9d4e-1a8c3a6b5d11",
  "source_creative_id": null,
  "video_url": null,
  "thumbnail_url": null,
  "duration_seconds": 30,
  "aspect_ratio": "9:16",
  "created_at": "2026-09-25T10:00:00.000Z",
  "credits_charged": 60
}

A video is usually ready in about five minutes. Poll GET /videos/{video_id} with backoff until status is completed or failed. A render that fails is refunded.

Animate a photo

Turn a completed Quick Shoot photo into a video. The choices match the app’s Animate dialog: 5 to 15 seconds, Portrait (9:16), Landscape (16:9) or Square (1:1), and an optional prompt.

curl --request POST \
  --url https://makelocalads.com/api/v1/videos \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "animation",
    "source_creative_id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
    "duration_seconds": 10,
    "aspect_ratio": "9:16",
    "prompt": "Slow push-in as steam rises from the cup."
  }'

A 10 second animation costs 20 credits. Poll it the same way.

Errors

Status	Code	Meaning
`400`	`invalid_request`	`audience_id` is missing from a UGC video or concepts request (send an audience or `null`)
`404`	`product_not_found`, `audience_not_found`, `concept_not_found`, `voice_not_found`, `creative_not_found`	Something you referenced is not available to you
`422`	`plan_required`	Your plan does not include Video Ads
`422`	`request_rejected`	For animation, the source is not a completed Quick Shoot photo
`422`	`insufficient_credits`	Not enough credits. Nothing was charged
`422`	`credit_limit_exceeded`	The video would cost more than `max_credits`

Start here

Build with LocalAds

Help

Before you start

1. Choose an audience

2. Choose a recipe

3. Generate and pick a concept

4. Pick a voice

5. Create the video

Animate a photo

Errors

​Before you start

​1. Choose an audience

​2. Choose a recipe

​3. Generate and pick a concept

​4. Pick a voice

​5. Create the video

​Animate a photo

​Errors

Before you start

1. Choose an audience

2. Choose a recipe

3. Generate and pick a concept

4. Pick a voice

5. Create the video

Animate a photo

Errors