Martini Generation API

Martini provides a typed client for asynchronous image and video generation. Requests are authenticated, validated, billed in olives, added to Generation History, and returned with durable output URLs.

To run a multi-step workflow saved from a canvas with the same key, see the Workflows API.

subscribe() uses polling. A failed or cancelled request ends polling with an error; it does not remain in a polling loop. It always generates immediately; draft mode is available only on queue.submit().

Each API key may have up to 300 active generations. Submit traffic is limited to 300 requests per 10 seconds and 600 requests per minute; excess requests return RATE_LIMITED.

Submit and status responses include olive_cost once pricing is available, and result responses always include it. An overlapping retry of the same idempotent submission can briefly omit the field while the original request is still being priced. This is the snapshotted charge in olives, so it does not change when model pricing changes. Martini applies any negotiated billing-organization, model, and resolution multiplier before rounding the charge to four decimal places. The same negotiated multipliers apply to generations in the Martini interface; MCP generations keep standard pricing.

Without destination options, Martini uses the defaults bound to the API key. The first key for an organization creates or reuses the private API Generations project and its Canvas 1.

Overrides require project write access and must resolve to the key’s billing organization. Projects without a canvas return CANVAS_NOT_FOUND.

Media URL fields accept:

• Public HTTPS URLs
• Martini-hosted HTTPS URLs
• Base64 data URLs in the form data:<mime>;base64,<bytes>

Martini validates type and content, then uploads data URLs to durable storage before billing, provider submission, or canvas persistence. Binary File and Blob values are not accepted directly in generation media fields; upload them as reusable assets first. Completed results contain durable Martini URLs, not expiring provider URLs.

Base64 adds roughly 33% to the media size. One 30 MB video becomes about 40 MiB in the request; two maximum-sized inline videos exceed the request-body limit. Use HTTPS URLs for large or multiple references.

Upload reusable project media before generation when you have a binary file, a large reference, or media you want to use across multiple requests. Uploads create visible canvas assets in the API key's default project and canvas, then return a stable Martini URL.

To upload into another accessible project, provide both projectId and canvasId. Upload destination overrides must include both values.

queue.submit() returns a Martini-owned public request ID. Provider operation IDs remain private. Returned response, status, and cancellation URLs use Martini API URLs. Status, result, and cancel calls must use the same API key and endpoint alias used at submission.

The same generations are also available as plain REST under /v1, the namespace the Workflows API uses: one resource describes a generation from draft to terminal state and carries its output once completed, so a caller polls one URL and never needs the endpoint alias to poll. Same key, same models, same billing and canvas placement as the queue methods above.

The whole /v1 surface, including the upload routes and every model’s input schema, is described by an OpenAPI 3.1 document at api.martini.film/v1/openapi.json (no authentication). Point a client generator or a coding agent at it for any language the SDKs do not cover.

Authenticate with Authorization: Bearer $MARTINI_API_KEY (or Key). The submit body carries the model input in its fal field names plus the Martini options that the queue methods send as headers:

Optional body fields: projectId, canvasId (requires projectId), placement: "auto", idempotencyKey, and mode: "draft". Poll GET /v1/generations/{id} until status is completed, failed, or cancelled. A draft never settles until POST /v1/generations/{id}/generate starts it.

Both clients wrap the five routes as generations.submit(), status(), cancel(), generate(), wait(), and subscribe(), plus models(). subscribe() and wait() return a failed or cancelled generation with its error rather than throwing; check output or status. In Python, generation.result() returns the typed output or raises GenerationFailedError.

Errors use JSON with a stable Martini code. Provider details are sanitized before they are returned.

This example uses duration: 'auto', allowing the model to select a 4–30 second take.

Nano Banana returns one image. Keep num_images: 1. Use the /edit endpoint for image references; video, audio, and PDF context are unsupported.