Async requests

Every call gets an ID that is also its billing ID: chatcmpl-… for chat, img_… for images and video_… for videos. The generation endpoints work with all of them.

Asynchronous requests

Videos are always asynchronous. Image requests become asynchronous when you send Prefer: respond-async:

curl https://api.geekidea.ai/v1/images/generations \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"model": "midjourney/midjourney-v8.2", "prompt": "a lighthouse at dawn, watercolor"}'

The response is 202 Accepted with a generation in queued status, the response header Preference-Applied: respond-async, and estimated_cost, the amount held from your balance until the job finishes.

Idempotency

Send Idempotency-Key (up to 255 characters) with asynchronous requests. Within a project, a key is accepted only once: if a network retry sends the same request again, you get the existing generation back, and nothing is held or generated twice.

Look up a generation

GET /v1/generations/{id} returns the current state:

Field	Description
`status`	`queued` → `in_progress` → `completed`, `failed` or `cancelled`
`output.videos` / `data`	Video or image results, with freshly signed links on every request
`usage`	Usage and cost once finished
`estimated_cost`	Amount on hold while queued or running
`billing_status`	`estimated`, `settled`, `refunded` or `adjusted`
`adjustments`, `net_cost`	Refunds or other corrections, and the final cost after them
`error_code`	Why it failed, for example `content_policy_violation` or `generation_timeout`
`latency_ms`, `api_key`, `project_id`, `metadata`	Details of the call

Poll every few seconds for images and every 10–15 seconds for videos, or use webhooks instead.

import time, requests

headers = {"Authorization": f"Bearer {api_key}"}
job = requests.get(f"https://api.geekidea.ai/v1/generations/{job_id}", headers=headers).json()
while job["status"] in ("queued", "in_progress"):
    time.sleep(10)
    job = requests.get(f"https://api.geekidea.ai/v1/generations/{job_id}", headers=headers).json()
print(job["status"], job.get("output"))

An API key can only see generations it created; anything else returns 404 generation_not_found. To see every call in your organization, use GET /v1/organization/generations with an admin key.

List generations

GET /v1/generations?type=video&status=completed&limit=20&after=video_… lists the calls made with your key, newest first, in the OpenAI list format (data, first_id, last_id, has_more). limit defaults to 20, maximum 100.

Cancel

POST /v1/generations/{id}/cancel cancels a job. You are charged only if the model provider charges for it:

Still queued: the job becomes cancelled right away. You are not charged and the hold is released.
Already running at the model provider: the response stays in_progress with cancel_requested_at set, and the cancellation is passed on to the provider. If the provider stops the job or it fails, it becomes cancelled and you are not charged. Some jobs can’t be stopped once they have started; if it completes anyway, it becomes completed, is charged as usual and the result is delivered.

Keep polling (or wait for the webhook) to see the final status. Cancelling again returns the same object; cancelling a completed or failed job returns 409 generation_not_cancellable.

Timeouts

Jobs that don’t finish within their deadline fail with generation_timeout and are not charged.

Get started

Generate

Workflows

Async and webhooks

Account

Asynchronous requests

Idempotency

Look up a generation

List generations

Cancel

Timeouts

​Asynchronous requests

​Idempotency

​Look up a generation

​List generations

​Cancel

​Timeouts

Asynchronous requests

Idempotency

Look up a generation

List generations

Cancel

Timeouts