Images

Uploaded assets — product photos, brand logos, lifestyle imagery — used during ad generation.

An image is an uploaded visual asset in your workspace. Images are referenced by ID from brands (logos), product variants (product photos), and ad outputs.

Mental model

You upload an image once and reference it by img_… ID elsewhere. The API processes uploads through a pipeline: extracts metadata, generates three thumbnail sizes (small, medium, large) in WebP, uploads to R2 storage, and returns URLs. Optional background enrichment runs after the upload returns.

ID prefix: img_.

Fields

Field	Type	Description
`id`	string	`img_…`
`src`	string	Public CDN URL of the original
`width` / `height`	number	Pixel dimensions
`format`	string	`png`, `jpeg`, `webp`, `gif`
`size_bytes`	number	File size in bytes
`alt_text`	string \| null	Accessibility text
`image_type`	string \| null	Semantic label (e.g., `product`, `logo`, `lifestyle`)
`is_ai_generated`	boolean	Flag for AI-produced assets
`logo_theme`	string \| null	`light` or `dark` for logos
`product_id`	string \| null	Optional product association
`thumbnail_small_src` / `thumbnail_medium_src` / `thumbnail_large_src`	string \| null	Pre-rendered WebP thumbnails
`created_at` / `updated_at`	string	ISO timestamps

Endpoints

Method	Path	Purpose
`POST`	`/v1/images`	Upload an image (multipart)
`GET`	`/v1/images`	List images
`GET`	`/v1/images/:id`	Get an image
`DELETE`	`/v1/images/:id`	Delete an image

Common patterns

Upload an image

Uploads are multipart/form-data. Send the file under file.

import { readFile } from "node:fs/promises";

const buffer = await readFile("./hero.png");
const form = new FormData();
form.append("file", new Blob([buffer], { type: "image/png" }), "hero.png");
form.append("image_type", "product");

const response = await fetch("https://api.staticadslab.com/v1/images", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
  body: form,
});
const { data } = await response.json();
console.log(data.id, data.src);

curl -s -X POST https://api.staticadslab.com/v1/images \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@./hero.png" \
  -F "image_type=product"

import requests

with open("./hero.png", "rb") as f:
    response = requests.post(
        "https://api.staticadslab.com/v1/images",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"file": ("hero.png", f, "image/png")},
        data={"image_type": "product"},
    )
print(response.json()["data"]["id"])

Pitfalls

Maximum body size is 15 MB (raw bytes). Compress aggressive PNG screenshots before upload.
The API never accepts base64 image data in JSON. Always upload binaries via multipart/form-data and reference by ID afterward.
Thumbnails may be null immediately after upload — they're generated as part of the upload pipeline. If you need them, re-fetch the image after a brief delay.

Prompt for your agent

Read https://www.staticadslab.com/docs/resources/images.mdx and write a function uploadImage(filePath, imageType) that returns the resulting image ID. Use multipart/form-data and the X-API-Key header.

Images

On this page