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

# From a moodboard

> Make or pick a moodboard, then shoot in its style or pick shots from its grid.

[← Photoshoots](/photoshoots/overview)

**Endpoints:** `POST https://makelocalads.com/api/v1/moodboards` and
`POST https://makelocalads.com/api/v1/photoshoots`
**Permissions:** create with `photoshoots:generate`, list with
`photoshoots:read`

A moodboard is a 3 x 3 grid of images in one style, made for a product. It is
free, and it can steer a photoshoot in two ways, like the Quick Shoot
moodboard dialog in the app: shoot in its style, or pick individual shots from
its grid.

## Usage notes

* Poll a new moodboard until its `status` is `completed` before using it; an
  unfinished one returns `422 moodboard_not_ready`.
* A moodboard can be made for the product you are shooting, or for a related
  one.
* Moodboards are free. The photoshoot costs 1 credit per requested image.

## Create or pick a moodboard

List the moodboards offered for a product: yours for it and for related
products, newest first, up to 60:

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

Or create one, with an optional idea and up to 8 reference images:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://makelocalads.com/api/v1/moodboards \
    --header "Authorization: Bearer $LOCALADS_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
      "idea": "Sunlit Mediterranean terrace, linen and terracotta."
    }'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://makelocalads.com/api/v1/moodboards",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.LOCALADS_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        product_id: "a1516a75-9be5-461a-93af-c1896a0a3127",
        idea: "Sunlit Mediterranean terrace, linen and terracotta.",
      }),
    },
  );

  const moodboard = await response.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://makelocalads.com/api/v1/moodboards",
      headers={
          "Authorization": f"Bearer {os.environ['LOCALADS_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
          "idea": "Sunlit Mediterranean terrace, linen and terracotta.",
      },
  )

  moodboard = response.json()
  ```
</CodeGroup>

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "7c1f2e10-4b8f-4a3c-9d7e-2f5a6b8c9d01",
  "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
  "status": "queued",
  "image_url": null,
  "style_name": null,
  "summary": null,
  "idea": "Sunlit Mediterranean terrace, linen and terracotta.",
  "created_at": "2026-09-25T10:00:00.000Z"
}
```

The request answers `202 Accepted`. Poll `GET /moodboards/{moodboard_id}`
until `status` is `completed`; its `image_url` is then the finished grid.

### Moodboard fields

<ParamField body="product_id" type="string" required>
  The product the moodboard is made for.
</ParamField>

<ParamField body="idea" type="string">
  What the moodboard should explore, 1 to 2,000 characters. Optional.
</ParamField>

<ParamField body="reference_image_urls" type="array">
  1 to 8 HTTPS reference images. Optional. An image that is only on your
  computer can be uploaded first with
  [Image uploads](/setup/image-uploads).
</ParamField>

## Shoot in the moodboard's style

Add `moodboard_id` to a Quick Shoot. Direction, look and count work as usual:
see [Quick Shoot](/photoshoots/quick-shoot).

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
  "quick_shoot": {
    "moodboard_id": "7c1f2e10-4b8f-4a3c-9d7e-2f5a6b8c9d01",
    "count": 5
  }
}
```

## Pick shots from the grid

Send `moodboard_shots` instead of `quick_shoot` or `template_id` to get one
photo per chosen cell, each in that cell's direction. Cells are numbered 0 to
8, left to right and top to bottom. Omit `cells` for all nine:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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",
    "moodboard_shots": {
      "moodboard_id": "7c1f2e10-4b8f-4a3c-9d7e-2f5a6b8c9d01",
      "cells": [0, 4, 8]
    }
  }'
```

### moodboard\_shots fields

<ParamField body="moodboard_shots.moodboard_id" type="string" required>
  A completed moodboard for this product or a related one.
</ParamField>

<ParamField body="moodboard_shots.cells" type="array">
  Grid cells to shoot, 0 to 8, left to right and top to bottom. 1 to 9 unique
  cells; defaults to all nine. One image, and one credit, per cell.
</ParamField>

Each cell is one image and one credit. The response is a photoshoot, polled
like any other: see [Get the photos](/photoshoots/results).

## Errors

| Status | Code | Meaning |
| - | - | - |
| 404 | `product_not_found`, `moodboard_not_found` | Not available to you |
| 422 | `moodboard_not_ready` | The moodboard is not completed, or was made for an unrelated product |

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