# Sandstorm API

> Generate on-brand images, video and audio, read the brand kit and library, and search competitor ads, over HTTP with one API key.

Base URL: https://sandbox.ads.dev
Auth: `Authorization: Bearer sk_live_…`. A key acts on one brand; send `Sandstorm-Brand: <brand id>` for another brand in the same organization.
Full schema: https://sandbox.ads.dev/openapi.json
SDKs: `npm install ads.dev` (TypeScript) and `pip install ads_dev` (Python).

## Get a key

If SANDSTORM_API_KEY is not set, run this in the project directory:

    curl -fsSL https://sandbox.ads.dev/login.mjs -o sandstorm-login.mjs && node sandstorm-login.mjs

It opens the person's browser to sign in to Sandstorm, makes a key, writes SANDSTORM_API_KEY and SANDSTORM_API_URL to ./.env and checks the key works. Options: --print (print the key instead), --org <id>, --brand <id>, --name "<label>", --env <file>, --no-open. With several organizations and no terminal to ask in, it lists them; run it again with --org. A person can also make a key at https://sandstorm-git-development-sandstorm-app.vercel.app/settings/api-keys. Never print or commit the key.

## Generate

POST /v1/generations with `{ "model": "<id>", "input": { … }, "webhook_url"?: "https://…" }`.
It answers a generation: `{ id: "gen_…", status: "queued" | "running" | "succeeded" | "failed" | "canceled", output: [{ id: "asset_…", type, url, … }], credits }`.
- Poll GET /v1/generations/{id} every 2 to 5 seconds until status is succeeded, failed or canceled, or
- send `Prefer: wait=60` (up to 200) to get the finished generation in the same call, or
- pass webhook_url and verify `Sandstorm-Signature: t=…,v1=…` (HMAC-SHA256 of "<t>.<body>" with the secret from GET /v1/webhooks/secret).
Media inputs take an asset id (asset_…) or an https URL; a URL is imported into the library first.
`name` is optional on every model: what the output is called in the library.
Send `Idempotency-Key` to retry safely. Failed generations are not charged.
Each model's full input schema: GET /v1/models/{id} → input_schema.

## Models

- `nano-banana-pro` (image, text-to-image): Photoreal images from a prompt: people, products and first frames for video. Up to 4K. Required: `prompt`. From $0.30 per image.
- `nano-banana-pro/edit` (image, image-edit): Change an image or combine several by instruction: a new background, color or setting. Required: `prompt`, `images`. From $0.30 per image.
- `nano-banana-2` (image, text-to-image): Faster than Pro for many variations, and the only one that makes 4:1 and 8:1 banners. Required: `prompt`. From $0.16 per image.
- `nano-banana-2/edit` (image, image-edit): Many edits or variations of images you already have, faster than Pro. Required: `prompt`, `images`. From $0.16 per image.
- `nano-banana-2-lite` (image, text-to-image): The fastest image model, for concepts, previews and lots of options before a final. Required: `prompt`. From $0.084 per image.
- `nano-banana-2-lite/edit` (image, image-edit): Quick drafts of an edit, and many options to choose from. Required: `prompt`, `images`. From $0.084 per image.
- `gpt-image-2.5-flare` (image, text-to-image): Images that carry copy and typography, follow an exact layout or need a transparent background. Required: `prompt`. From $0.178 per image.
- `gpt-image-2.5-flare/edit` (image, image-edit): Ads built around your product or logo images, with the copy set in the image. Up to 16 references. Required: `prompt`, `images`. From $0.178 per image.
- `gpt-image-2.5-sunburst` (image, text-to-image): The slower, precision GPT model, for intricate detail and final passes. Required: `prompt`. From $0.178 per image.
- `gpt-image-2.5-sunburst/edit` (image, image-edit): Precision edits from up to 16 reference images. Required: `prompt`, `images`. From $0.178 per image.
- `seedream-5-pro` (image, text-to-image): Apparel and product imagery, swimwear included, and in-image text in 14 languages. Required: `prompt`. From $0.09 per image.
- `seedream-5-pro/edit` (image, image-edit): Targeted changes that keep the rest of the frame, from up to 10 images. Required: `prompt`, `images`. From $0.09 per image.
- `seedream-5-lite` (image, text-to-image): Faster than Pro, for drafts and 3K or 4K finals. Required: `prompt`. From $0.07 per image.
- `seedream-5-lite/edit` (image, image-edit): Fast edits from up to 14 images, at up to 4K. Required: `prompt`, `images`. From $0.07 per image.
- `seedream-5-pro/layers` (image, layers): Split one image into editable layers: background, product, headline and logo. Required: `image`. From $0.068 per layer.
- `topaz/upscale` (image, upscale): Enlarge an image and recover sharpness without inventing content. Required: `image`. From $0.16 per image.
- `seedance-2.5/text-to-video` (video, text-to-video): A clip from a prompt alone, with sound, speech and music. 4 to 30 seconds. Required: `prompt`. From $0.129 per second.
- `seedance-2.5/image-to-video` (video, image-to-video): Bring a still to life, or join two frames with motion. 4 to 30 seconds. Required: `prompt`, `start_image`. From $0.129 per second.
- `seedance-2.5/reference-to-video` (video, reference-to-video): Motion that keeps the look of images, the movement of clips or the sound of audio you pass. Required: `prompt`. From $0.129 per second.
- `seedance-2.5/finish` (video, draft-finish): Finish a 480p draft at 1080p, within 7 days of making it. Required: `draft`. From $0.129 per second.
- `kling-3-pro/image-to-video` (video, image-to-video): A clip that opens on your image and can end on a second one. Required: `start_image`. From $0.224 per second.
- `kling-o3-pro/reference-to-video` (video, reference-to-video): Keeps a person, product or character true to up to 4 reference images. Required: none. From $0.224 per second.
- `gemini-omni-flash/text-to-video` (video, text-to-video): A clip from a prompt, from a 360p draft to a 4K take. Required: `prompt`. From $0.06 per second.
- `gemini-omni-flash/image-to-video` (video, image-to-video): A clip that opens on your image, from 360p to 4K. Required: `prompt`, `start_image`. From $0.06 per second.
- `gemini-omni-flash/reference-to-video` (video, reference-to-video): A clip guided by up to 10 images or 3 short clips. Required: `prompt`. From $0.06 per second.
- `gemini-omni-flash/edit` (video, video-edit): Change one thing in a clip of 10 seconds or less, such as the background or the weather. Required: `prompt`, `video`. From $0.06 per second.
- `sync-3/lipsync` (video, lipsync): Re-sync the speaker’s lips to new audio: dubs, new lines and fixed takes. Required: `video`, `audio`. From $16.00 per minute.
- `elevenlabs/voiceover` (audio, voiceover): Speak a script aloud in any library voice. Required: `text`. From $0.16 per 1K characters.
- `elevenlabs/music` (audio, music): Background tracks, jingles and songs, with or without vocals. Required: `prompt`. From $1.20 per minute.
- `elevenlabs/sound-effects` (audio, sound-effects): Impacts, ambiences, foley and interface sounds from a description. Required: `prompt`. From $0.004 per second.
- `elevenlabs/voice-changer` (audio, voice-change): Re-voice a recording into another voice, keeping its timing and emotion. Required: `audio`, `voice`. From $0.004 per second.
- `elevenlabs/voice-isolator` (audio, voice-isolation): Pull the voice out of a recording, removing noise, music and ambience. Required: `audio`. From $0.20 per minute.
- `minimax/music` (audio, music): Songs sung from your lyrics, or instrumentals. Required: `prompt`. From $0.30 per call.
- `sonilo/music` (audio, music): Instrumental music to the exact second, trained only on licensed music and cleared for ads. Required: `prompt`, `duration`. From $0.005 per second.

## Read

- GET /v1/brand: the brand kit (voice, audience, positioning, rules, colors, type, fonts, logos with URLs)
- GET /v1/assets?type=image&limit=20&cursor=…: the library; POST /v1/assets { url, name? } imports a file
- GET /v1/offers, GET /v1/offers/{id}: products and services with variants and photos
- GET /v1/characters: people, products and styles to keep consistent
- GET /v1/voices?query=…: voices for elevenlabs/voiceover
- GET /v1/advertisers?query=Liquid Death, then GET /v1/ads?advertiser=advertiser_…&status=active: competitor ads
Lists answer `{ object: "list", data, has_more, next_cursor }`; pass next_cursor as cursor for the next page.

## Errors

`{ error: { type, code, message, param?, request_id } }` with 400 invalid input, 401 bad key, 402 not enough credits, 403 brand not allowed, 404 not found, 409 already finished, 422 Idempotency-Key reused, 429 more than 300 requests a minute, 503 retry.

## Pricing

Every model lists dollars per unit in GET /v1/models. A call is charged once it succeeds, rounded up to the next $0.05.