---
title: "Storyboard Bulk Images"
method: POST
path: "/api/v1/asset/storyboard-bulk-images"
tags: ["assets"]
---

# Storyboard Bulk Images

`POST /api/v1/asset/storyboard-bulk-images`

## Request

- Base URL: `https://api.brandbooster.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.brandbooster.ai/api/v1/asset/storyboard-bulk-images`
- Auth: one of:
  - API key in header `X-Internal-Api-Key`
  - API key in query parameter `api_key`

Generate a batch of storyboard images in one call (async). No user auth.

Items may reference other items in the SAME batch, so a first_frame can
reuse the character and product images generated alongside it. The worker
runs in dependency order — anything with no references goes first, then
whatever depended on it.

Headers:
    x-api-key: <STORYBOARD_API_KEY>   (or ?api_key=<STORYBOARD_API_KEY>)

Body:
    storyboard_id: your run identifier — optional, echoed back and stored
    items[]:
        angle:      angle slug, e.g. "a1"
        beat:       beat id, e.g. "b01"; null for angle-level (char/product)
        slot:       char | product | first_frame | end_frame — also the filename
        ratio:      "9x16" | "1x1" | "4x5" … (URL-safe, no colons)
        model:      nanobanana | nanobanana_pro | nanobanana_2 | seedream | gpt_image_2
        prompt:     full generation prompt
        references: keys of other items in this batch to use as reference
                    images, in @image1..@imageN order.
                    Key is "{angle}/{slot}" or "{angle}/{beat}/{slot}".

Each result is saved to:
    storyboard/{task_id}/{angle}/{slot}/{ratio}/{slot}.png            (beat null)
    storyboard/{task_id}/{angle}/{beat}/{slot}/{ratio}/{slot}.png     (beat set)

Returns:
    dict: task_id, storyboard_id, accepted, status

## Request body

- StoryboardBulkImageRequestDTO: Request DTO for batch image generation. Items may reference other items in the SAME batch by their `key` (see StoryboardBulkItemDTO.key). The worker generates in dependency order so a referenced image exists before the item that needs it. Hosted URLs from outside the batch go in `reference_image_urls` and take no part in ordering.
  - `storyboard_id` string, nullable
  - `items` StoryboardBulkItemDTO[], required
    - `id` string, nullable
    - `angle` string, nullable
    - `beat` string, nullable
    - `slot` string, nullable
    - `ratio` string, nullable
    - `model` string, nullable
    - `prompt` string, required
    - `references` string[], nullable
    - `reference_image_urls` string[], nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

## Changes

> 35 revisions in range; 1 not diffed.

- **2026-10-26** `b7c090567a88`: 1 info
  - the `model` request property default value changed from `gpt_image_2` to `seedream`

[Operation history](https://skmtc.dev/brandbooster/apis/fastapi/changes/api/v1/asset/storyboard-bulk-images/post.md)

---

[API](https://skmtc.dev/brandbooster/apis/fastapi.md) - [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) - [OpenAPI document](https://skmtc.dev/brandbooster/apis/fastapi/revisions/8e8c18c2dc35?raw)