Generate images with the API: tasks, polling and webhooks

How image jobs work

Image, video and audio requests return a task straight away instead of making you wait on an open connection. You then poll the task, or receive a webhook when it finishes. While it runs, an estimate is held from your credit; when it finishes, the hold is released and the real charge is taken. Failed tasks cost nothing.

1. Start the task

curl https://omni-api.rcinc.app/v1/images/generations \
  -H "Authorization: Bearer $OMNI_KEY" -H "content-type: application/json" \
  -d '{"model":"ai33/gpt-image-2","prompt":"Isometric illustration of a tiny data centre on a cloud","aspect_ratio":"1:1","resolution":"2K"}'

The response contains "id": "task_…" and "status": "pending".

2a. Poll for the result

import os, time, requests

KEY = os.environ["OMNI_KEY"]
headers = {"Authorization": f"Bearer {KEY}"}
task_id = "task_…"
while True:
    task = requests.get(f"https://omni-api.rcinc.app/v1/tasks/{task_id}", headers=headers, timeout=30).json()
    if task["status"] in ("done", "failed"):
        break
    time.sleep(4)
print(task["output"]["images"][0]["url"] if task["status"] == "done" else task["error"])

2b. Or receive a webhook

Add "webhook_url": "https://your-app.example.com/hooks/omni" to the request. When the task finishes, Omni POSTs { "type": "task.done", "data": <task> } with an x-omni-signature header. Verify it with the webhook secret from your dashboard:

import crypto from "node:crypto";

function verify(rawBody, timestamp, signature, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

3. Download the image

Result links expire after a while, so copy the file to your own storage when the task finishes.

Using reference images

Pass up to ten public image links in reference_urls and refer to them in the prompt as @img1, @img2 and so on. Each image can be up to 5 MB.

Picking a model

Model	Good for
`ai33/gpt-image-2`	General illustration and text in images, lowest price
`ai33/bytedance-seedream-5-pro`	Keeping characters and products consistent across references
`kie/google/nano-banana`	Fast edits and photo-style images

All current models and prices are listed at GET https://omni-api.rcinc.app/v1/models.