Generate with the API

The API runs at https://shotz.co/api/v1. Every request needs a workspace API key in the Authorization header, and every answer is JSON.

Authorization: Bearer sk_live_…

Generating takes two calls: one to start, then one you repeat until the takes are ready.

Start a generation

POST https://shotz.co/api/v1/generations

Send an Idempotency-Key header with a unique value for each new generation (for example, a UUID). If the connection fails or the API returns 503, repeat the same body and key. The retry returns the original generation without creating or charging for another one. Keys are scoped to the API key and accept 1–200 visible ASCII characters. Reusing a key with a different body returns 409. The header is optional; requests without it create a new generation each time.

Send a JSON body (with Content-Type: application/json):

• kind (required): video, image, audio, 3d or world.
• prompt: what to make, up to 4,000 characters. Required unless you send a skill. A skill’s slug with a slash in front, like /crash-zoom, works in the prompt as it does in the card, wherever you put it. Some models take fewer characters than that, counting the words a skill adds. A prompt that’s too long for the model is refused with 400 and nothing is spent, never cut short.
• skill: a skill’s slug, the last part of its address on shotz.co/skills, such as crash-zoom. The skill adds its own direction to your prompt, the same as picking it in the card. It goes in front of your words, as /crash-zoom. You can send a skill with no prompt, and it makes its shot on its own. A slug that isn’t a skill is refused.
• model: a model id from GET /api/v1/models. Without one, video uses kling-3.0 and images nano-banana-pro. 3D defaults to hunyuan-3d-3.1, Worlds to marble-1.1. Audio needs a model. The model has to make the kind you asked for.
• count: how many takes of the prompt to make, 1 to 4. Defaults to 1.
• shape: 16:9, 9:16, 1:1 or 4:5. Defaults to 16:9 for video and 1:1 otherwise.
• seconds: how long, 1 to 60. Each model makes certain lengths up to its own maximum, and the nearest one is used. Video defaults to 5.
• quality: an output quality, such as 720p, 1080p or 4K for video, or 1K or 2K for images. Use a qualities option from GET /api/v1/models for the selected model. Other values are handled by that model's rules: some map to an available quality, while others are refused. Wan 2.2 Fast requires one of its listed qualities; its 1080p and 4K outputs are learned upscales from native 720p generation.
• sound: true or false, for a video model's native audio. This does not enable or disable the separate effects option.
• effects: true explicitly adds generated sound effects and ambience on a compatible model such as Wan 2.2 Fast. It defaults to off and has an additional credit cost, included in the generation's total. These effects follow the prompt; they do not generate dialogue, lip sync or guaranteed synchronization to actions in the video. Use effects: false for a silent Wan 2.2 Fast clip, including when sound was set on an older request. Models without this option refuse effects: true before spending credits.
• projectId: a project in the workspace to file the generation under.
• fields: Library field values to set on every file the generation makes, by key, like {"sku": "4410", "status": "Draft", "channels": ["Shopify"]}. They’re checked before anything starts: a key the workspace has no field for, or a value that doesn’t fit (a choice the field doesn’t have), is a 400 and nothing is spent. Each file gets them once it lands in the Library.

For example:

{"kind": "image", "prompt": "A red kite over the dunes", "model": "flux-3-image"}

A generation that starts answers 202 with:

• id: the generation, to check on.
• outputs: one for each take, with its id and status (queued).
• credits: what the takes cost in total.
• status: queued.

Check on it

GET https://shotz.co/api/v1/generations/{id}

The answer has the generation’s id, kind, prompt, created and status, and an outputs list, one for each take. The prompt is your own words, with any skill shown as its /slug and without the skill’s direction. The generation’s status is:

• generating while any take is queued or running
• ready when every take is ready
• partly ready when some are ready and the rest failed or were cancelled
• failed when none made it

Each output has its id, model, status (queued, generating, ready, failed or canceled), progress (0 to 100), credits, and error, which says why if it failed. A failed take gives its credits back; a canceled one does only if the model hadn’t started it. A ready take also has mediaId, the file in your Library, with url, a download link that works for at least an hour, and mime, the file type.

Check every few seconds until the status isn’t generating.

Credits

A generation spends the key’s workspace credits, at the same price as in the app: each model’s price is in GET /api/v1/models. The free daily images on FLUX.2 klein aren’t free through the API: they cost the model’s usual credits. If a take fails, its credits come back on their own. If there aren’t enough credits, the generation doesn’t start: see API errors.

What you make lands in the workspace’s Library, like anything made in the app.

Spatial generations

Use kind: "3d" for a textured object or kind: "world" for an explorable environment. These take a description without shot skills or a video project. Keep 3D prompts to 1,024 characters. For example:

{"kind":"world","prompt":"A sunlit greenhouse with winding stone paths","model":"marble-1.1"}

Completed spatial files are saved to the Library and downloaded as GLB (3D) or SPZ (Worlds). Their interactive previews open in Shotz.