Async generation

Some models take minutes to make an image, and some clients give up on a tool call long before that. An async generation job starts a generate_image request, gives you an id straight away, and keeps running even if your client disconnects. You check on it later, or cancel it.

The same jobs are available through MCP tools and the REST API.

Step	MCP tool	REST
Start	start_generation	POST /api/generations/start
Check	get_generation_status	GET /api/generations/:id
Cancel	cancel_generation	POST /api/generations/:id/cancel

Start a job

The request body takes the same fields as generate_image (one request per job), plus two optional fields:

Field	Description
idempotency_key	Up to 200 characters. Sending the same key again returns the same job instead of starting a new one. Over REST you can send it as the Idempotency-Key header instead
sync_timeout_ms	Wait up to this many milliseconds (max 25000) for the job to finish. If it finishes in time, the images come back in the response

curl -X POST "https://gobananasai.com/api/generations/start" \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lighthouse-001" \
  -d '{ "prompt": "a lighthouse at dusk, oil painting", "model_id": "gemini-pro-image" }'

Over REST, an unfinished job answers 202 with executionId, status, statusUrl and cancelUrl. A job that finished within sync_timeout_ms answers 200 with the full status, including images.

Requests that could never succeed, such as an unknown model or a character you do not own, are rejected with a 400 before a job is created.

project and tags work as on generate_image: the job files its images under them when it finishes. Over MCP, without project, the images go to the project of the folder you work in; that needs the local connector (the gobananas-mcp STDIO proxy, 1.4.0 or later), and remote HTTP connections and REST send no folder. A bad project or tag name is rejected before a job is created (400 with invalid_project_name or invalid_tag_name; invalid params over MCP). The job's status does not report a project; use get_image_info (or GET /api/images/:id) on its images. If they could not be filed, the status lists a warning.

If a job's runner is interrupted after saving images, the job settles from them at its deadline (12 + 2 minutes after it started) and files them then. Its explicit project is applied again, even over a move made in between, and tags removed in between are added again.

project and tags are no part of the request for idempotency: a retry with the same key returns the same job. A project or tags added on the retry do not apply to a job that already reached its runner; if the first handoff was lost, the retry's project and tags are used.

Limits

• 3 unfinished jobs per workspace. A fourth start is rejected with 429 until one finishes or is cancelled.
• A job has 12 minutes to generate. Anything still unfinished after 14 minutes is settled from the images it managed to store.

Check a job

GET /api/generations/:id (or get_generation_status with execution_id) returns:

Field	Description
status	pending, running, completed, failed or cancelled
progressPercent, currentStep	Progress so far
logEntries	The job's log
errorMessage	Why it failed, when it did
images	Once completed: each image's id, fullUrl, thumbnailUrl, size, format, prompt and modelId

Poll until the status is completed, failed or cancelled.

Cancel a job

POST /api/generations/:id/cancel (or cancel_generation). A job that has not started running never runs; a running job is stopped and stores nothing. If the job had already finished, REST answers 409 and the MCP tool returns cancel_requested: false.

Idempotency

Same key, and the earlier job is...	Result
pending, running or completed	The same job comes back (replayed: true over MCP)
failed or cancelled	409 IDEMPOTENCY_CONFLICT; use a new key
Started by another caller	409 IDEMPOTENCY_CONFLICT

Who can see a job

Only the caller that started a job can check or cancel it: the same API key, or the same OAuth user and client. Anyone else, including other members of the workspace, gets 404 Generation not found. OAuth clients need the images:generate scope to start or cancel a job and images:read to check one.

Related

• Generation tools
• API overview