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 a JSON body (with Content-Type: application/json):

• kind (required): video, image or audio.
• prompt (required): what to make, up to 4,000 characters.
• model: a model id from GET /api/v1/models. Without one, video uses kling-3.0 and images nano-banana-pro. Audio needs a model. The model has to make the kind you asked for.
• takes: 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.
• sound: true or false, for video models that make sound.
• projectId: a project in the workspace to file the generation under.

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.
• takes: the ids of its takes.
• 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 a takes list. 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 take 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 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. 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.