Create a photoshoot

A photoshoot generates new images for one of your products. Use a template when you want a reusable set of shots. Use Quick Shoot when you want to give direct creative direction. Generation runs asynchronously. Each requested output consumes one credit.

Before you start

You need:

an API key with photoshoots:generate
a product with at least one image
enough credits for every requested output

For template photoshoots, the product and template must belong to the same brand.

Upload a local reference image

Quick Shoot and template requests accept image URLs. If a reference is only on your computer, upload it first:

curl --request POST \
  --url "https://makelocalads.com/api/v1/uploads/images" \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --form "file=@/path/to/reference.jpg"

The response contains a durable url:

{
  "url": "https://assets.makelocalads.com/public-api/example/images/a0423594-2be3-44f7-b962-2259f6eeb9e4.jpg",
  "content_type": "image/jpeg",
  "width": 1400,
  "height": 1050,
  "size_bytes": 381214
}

Use that url in quick_shoot.direction.image_urls or a template’s image_urls. Upload one image per request. JPG, PNG, WebP, HEIC, and HEIF are supported up to 10 MB. Base64 and JSON data URLs are not supported. Existing public HTTPS image URLs can still be used directly; LocalAds copies accepted images into its own storage.

Create a template

Create a reusable template pack from one or more HTTPS image URLs. The product_id determines which brand can use the template.

curl --request POST \
  --url https://makelocalads.com/api/v1/templates \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "title": "Studio essentials",
    "image_urls": [
      "https://assets.makelocalads.com/public-api/example/images/template-shot-1.jpg",
      "https://assets.makelocalads.com/public-api/example/images/template-shot-2.jpg"
    ]
  }'

The response returns 201 Created and the template. LocalAds keeps a stable copy of each supplied image, so the template does not depend on the original URLs remaining available. Each shot keeps the same aspect ratio as its source image. You can use its id in a template photoshoot request.

Generate from a template

1. Choose a template

List the photoshoot templates available to the product’s brand:

curl "https://makelocalads.com/api/v1/templates?brand_id=1423f915-beca-4c53-a5e4-7c8c99537be9&limit=20" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"

{
  "data": [
    {
      "id": "photoshoot-shot-pack:38b66c64-e76f-483f-a185-2d377ee2c5eb",
      "brand_id": "1423f915-beca-4c53-a5e4-7c8c99537be9",
      "title": "Studio essentials",
      "preview_url": "https://cdn.example.com/template-preview.jpg",
      "shot_count": 4,
      "created_at": "2026-07-20T10:00:00.000Z",
      "updated_at": "2026-07-20T10:05:00.000Z"
    }
  ],
  "next_cursor": null
}

Retrieve one template to inspect its ordered shots and output dimensions:

curl "https://makelocalads.com/api/v1/templates/photoshoot-shot-pack%3A38b66c64-e76f-483f-a185-2d377ee2c5eb" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"

2. Start the photoshoot

curl --request POST \
  --url https://makelocalads.com/api/v1/photoshoots \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "template_id": "photoshoot-shot-pack:38b66c64-e76f-483f-a185-2d377ee2c5eb"
  }'

Do not include quick_shoot when you provide template_id.

Create a Quick Shoot

Quick Shoot mirrors the controls in the LocalAds workspace. You can choose a look and output count, then optionally add direction as text, images, or both.

curl --request POST \
  --url https://makelocalads.com/api/v1/photoshoots \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "quick_shoot": {
      "direction": {
        "text": "Place the product on a stone pedestal in warm sunlight.",
        "image_urls": [
          "https://assets.makelocalads.com/public-api/example/images/a0423594-2be3-44f7-b962-2259f6eeb9e4.jpg"
        ]
      },
      "look": "standard",
      "count": 3
    }
  }'

const response = await fetch("https://makelocalads.com/api/v1/photoshoots", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOCALADS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    product_id: "a1516a75-9be5-461a-93af-c1896a0a3127",
    quick_shoot: {
      direction: {
        text: "Place the product on a stone pedestal in warm sunlight.",
        image_urls: ["https://assets.makelocalads.com/public-api/example/images/a0423594-2be3-44f7-b962-2259f6eeb9e4.jpg"],
      },
      look: "standard",
      count: 3,
    },
  }),
});

const photoshoot = await response.json();

direction is optional. When included, it must contain text or at least one image URL. You can attach up to eight HTTPS images. For third-party URLs, the images must work without cookies or authorization headers.

`look`	Workspace label	Output size
`standard`	Standard	Square, 1024x1024
`close_up`	Close-up	Square, 1024x1024
`lifestyle`	Lifestyle	Square, 1024x1024
`out_of_the_box`	Out of the box	Square, 1024x1024
`retro`	Retro	Card, 1200x1800 at 300 DPI

count can be 1, 3, 5, 8, or 15. It defaults to 1; look defaults to standard. Do not include template_id when you provide quick_shoot.

The retro look

retro is a generative look. Instead of applying a fixed treatment to the product, it reads the product first, then invents a different printed scene for every output in the shoot: mid-century Indian print culture, souvenir and advertising cards, halftone and faded ink. Three things behave differently from the other looks:

Output is a print-ready card. Every image is 1200x1800 at 300 DPI, which is 4 x 6 inches: the artwork mounted on aged paper with the card’s line set in italics underneath it. Send it to a printer as it arrives.
direction.image_urls are ignored. The look composes each scene from the product itself. direction.text is still read and used as guidance.
The first image takes longer. The look derives a brief and renders one shared reference packshot before any output starts, which adds roughly a minute to the shoot. Later outputs arrive at the usual pace.

Ask for more than one output when you use it. Each card is a distinct format, so a shoot of 5 or 8 shows the range; a shoot of 1 shows one card and none of the variety the look exists for.

curl --request POST \
  --url https://makelocalads.com/api/v1/photoshoots \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "quick_shoot": {
      "look": "retro",
      "count": 5
    }
  }'

For production integrations, you can optionally include an Idempotency-Key header. If a network failure makes you retry a request, reuse the same key to avoid creating and charging for a duplicate photoshoot:

--header "Idempotency-Key: photoshoot-order-1042"

Omitting the header creates a new photoshoot on every request. LocalAds returns 202 Accepted with the durable photoshoot resource: The example below is a template photoshoot. Quick Shoot responses use the same shape with template_id set to null.

{
  "id": "e8766ffd-66f7-47c9-86bc-0d93e6868d06",
  "brand_id": "1423f915-beca-4c53-a5e4-7c8c99537be9",
  "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
  "template_id": "photoshoot-shot-pack:38b66c64-e76f-483f-a185-2d377ee2c5eb",
  "status": "queued",
  "outputs": [
    {
      "id": "19025a65-5395-41c9-af90-d7cca7fb6421",
      "position": 1,
      "status": "queued",
      "image_url": null,
      "width": null,
      "height": null,
      "caption": null
    }
  ],
  "created_at": "2026-07-24T15:00:00.000Z",
  "updated_at": "2026-07-24T15:00:00.000Z"
}

Retrieve results

Poll the URL in the Location response header:

curl https://makelocalads.com/api/v1/photoshoots/e8766ffd-66f7-47c9-86bc-0d93e6868d06 \
  --header "Authorization: Bearer $LOCALADS_API_KEY"

Completed outputs appear while the remaining shots continue:

{
  "id": "e8766ffd-66f7-47c9-86bc-0d93e6868d06",
  "brand_id": "1423f915-beca-4c53-a5e4-7c8c99537be9",
  "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
  "template_id": "photoshoot-shot-pack:38b66c64-e76f-483f-a185-2d377ee2c5eb",
  "status": "in_progress",
  "outputs": [
    {
      "id": "19025a65-5395-41c9-af90-d7cca7fb6421",
      "position": 1,
      "status": "completed",
      "image_url": "https://cdn.example.com/generated-shot-1.png",
      "width": 1024,
      "height": 1024,
      "caption": null
    },
    {
      "id": "4f52bad2-2da3-4b36-93ac-03788f35daca",
      "position": 2,
      "status": "in_progress",
      "image_url": null,
      "width": null,
      "height": null,
      "caption": null
    }
  ],
  "created_at": "2026-07-24T15:00:00.000Z",
  "updated_at": "2026-07-24T15:00:04.000Z"
}

Stop polling when the photoshoot status is completed, failed, or canceled. Use backoff between requests rather than polling continuously. caption carries the line printed in italics under the artwork. Only the retro look writes one; every other look and every template shot returns null.

Retrieve a product’s photoshoot creatives

You can later retrieve every completed photoshoot image for the product without remembering individual photoshoot IDs:

curl "https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/creatives?type=photoshoot" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"

Last modified on August 12, 2026

Start here

Build with LocalAds

Help

Before you start

Upload a local reference image

Create a template

Generate from a template

1. Choose a template

2. Start the photoshoot

Create a Quick Shoot

The retro look

Retrieve results

Retrieve a product’s photoshoot creatives

​Before you start

​Upload a local reference image

​Create a template

​Generate from a template

​1. Choose a template

​2. Start the photoshoot

​Create a Quick Shoot

​The retro look

​Retrieve results

​Retrieve a product’s photoshoot creatives

Before you start

Upload a local reference image

Create a template

Generate from a template

1. Choose a template

2. Start the photoshoot

Create a Quick Shoot

The retro look

Retrieve results

Retrieve a product’s photoshoot creatives