Asynchronous image generation

Submit an image task to receive a task ID, query its status, then download the images. You can also receive a completion webhook. The entire workflow uses the API; no website visit is required. The base URL is https://api.yomiapi.com. The paths below already contain /v1; do not add it twice.

Use an API Key with access to the selected model, an available route, and sufficient balance. Store it on your server. Use these headers for submission; queries and downloads also require a valid Bearer Key. Prefer the submission key; another valid key belonging to the same account can also download images.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Asynchronous tasks are not enabled by stream: true. Software that only supports synchronous image generation must add submission, polling, and download logic; changing the URL alone is insufficient.

Supported models and resolutions

The standard gpt-image-2.5 continues to use its existing synchronous endpoint and does not support the asynchronous endpoints or webhooks in this guide.

GPT: use size values 1024x1024 for 1K, 2048x2048 for 2K, and 3840x2160 or 2160x3840 for 4K. 4096x4096 is not supported. Custom dimensions must be multiples of 16, with a maximum side of 3840, an aspect ratio no greater than 3:1, and 655360–8294400 total pixels.

Gemini: imageSize uses uppercase 1K, 2K, or 4K; Lite supports only 1K. An example aspectRatio is 1:1. A resolution tier does not imply identical pixel dimensions across aspect ratios.

Grok: resolution uses lowercase 1k or 2k. Text-to-image supports square images with aspect_ratio set to 1:1. Omit aspect_ratio for reference-image edits. GPT, Gemini, and Grok output one image per task; reference images are inputs, not additional outputs.

Midjourney: the current tier is 1K; omit size or use 1024x1024. n: 1 means one task, which currently usually returns four images and is billed as one task. Use the actual response array to determine the image count.

1. Submit a task

The requests below explicitly select 1K. Your account must have access to the selected model; Gemini specifies the model ID in the request path.

GPT Image

POST /v1/async/images/generations

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A cat wearing a top hat",
  "size": "1024x1024",
  "n": 1
}

GPT image edits

POST /v1/async/images/edits

{
  "model": "gpt-image-2.5-flare",
  "prompt": "Keep the product, change the background to white",
  "images": [
    "https://example.com/product.png"
  ],
  "size": "1024x1024",
  "n": 1
}

Use either image or images with a non-empty array. Entries may be HTTP/HTTPS URLs, data:image/png;base64,... data URLs, plain Base64, or {"url":"https://..."} / {"image_url":"https://..."} URL objects. Reference count does not change the n: 1 output count. This async endpoint accepts JSON only, not binary multipart; JSON mask is unsupported. The platform request-body limit still applies.

Gemini

POST /v1/async/gemini/models/gemini-3.1-flash-image-preview:asyncGenerateContent

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "A cat wearing a top hat"
        }
      ]
    }
  ],
  "generationConfig": {
    "imageConfig": {
      "imageSize": "1K",
      "aspectRatio": "1:1"
    }
  }
}

Reference images use the same Gemini async endpoint. In contents[].parts[], add inlineData (with mimeType and Base64 data) or fileData (with fileUri). The snake_case forms inline_data / file_data and mime_type / file_uri also work. For example, add this part to the parts array above:

{"fileData":{"mimeType":"image/png","fileUri":"https://example.com/reference.png"}}

Grok

POST /v1/async/grok/images/generations

{
  "model": "grok-imagine-image-quality",
  "prompt": "A cat wearing a top hat",
  "resolution": "1k",
  "aspect_ratio": "1:1",
  "n": 1
}

Grok image edits

POST /v1/async/grok/images/edits

{
  "model": "grok-imagine-image-quality",
  "prompt": "Keep the product, change the background to white",
  "images": [
    {
      "type": "image_url",
      "url": "https://example.com/product.png"
    }
  ],
  "resolution": "1k",
  "n": 1
}

Pass one reference object in image, or an array of 1–3 objects in images; do not send both fields. Object format: {"type":"image_url","url":"https://..."} reference objects. Only URLs are supported. Set resolution to 1k or 2k and n to 1; omit aspect_ratio for edits.

Midjourney

POST /v1/async/midjourney/submit/imagine

{
  "model": "midjourney",
  "prompt": "A cat wearing a top hat",
  "size": "1024x1024",
  "n": 1
}

Runnable submission example

The curl examples use Bash/zsh syntax. Set YOMI_API_KEY in your environment before submitting. The query and download examples below use the same variable.

curl --fail-with-body 'https://api.yomiapi.com/v1/async/images/generations' \
  -H "Authorization: Bearer $YOMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-image-2.5-flare","prompt":"A cat wearing a top hat","size":"1024x1024","n":1}'

Submission response

Successful submissions currently return HTTP 200, which means accepted, not completed. GPT, Gemini, and Grok return taskID; Midjourney returns task_id. Save the task ID, model, and endpoint family, as query responses do not include the model. Response examples show key fields only, with illustrative IDs and timestamps; createdAt is in Unix seconds.

{
  "taskID": "task_EXAMPLE",
  "status": "queued",
  "createdAt": 1790200000
}

{
  "task_id": "task_EXAMPLE",
  "status": "SUBMITTED"
}

2. Query a task

Replace task_EXAMPLE with the returned task ID. Use a valid API Key, poll every 5–10 seconds, and stop after success or failure.

curl --fail-with-body 'https://api.yomiapi.com/v1/async/image-tasks/task_EXAMPLE' \
  -H "Authorization: Bearer $YOMI_API_KEY"

On success, read resultImages for GPT, Gemini, and Grok, or images for Midjourney. Iterate the returned array rather than constructing image numbers. Do not use the progress percentage alone to determine success.

{
  "taskID": "task_EXAMPLE",
  "status": "success",
  "createdAt": 1790200000,
  "resultImages": [
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-0/content"
    }
  ]
}

{
  "task_id": "task_EXAMPLE",
  "status": "SUCCESS",
  "images": [
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-1/content"
    },
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-2/content"
    },
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-3/content"
    },
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-4/content"
    }
  ]
}

Failure and uncertain states

Stop polling on failure. The first three families provide an explanation in statusMessage; Midjourney uses error.

{
  "taskID": "task_EXAMPLE",
  "status": "failed",
  "createdAt": 1790200000,
  "statusMessage": "Image generation failed"
}

{
  "task_id": "task_EXAMPLE",
  "status": "FAILURE",
  "images": [],
  "error": "Midjourney generation failed"
}

unknown / UNKNOWN means the current state is uncertain, not failed. Keep the task ID and poll less frequently; contact support if it persists. Retry temporary query failures with backoff. A client-side waiting timeout does not mean the task was cancelled.

A timed-out submission POST may already have been accepted. Do not blindly resubmit, which could generate and charge for another task. Query first if you have an ID; otherwise retain the request time and contact support if acceptance is unclear. Submission is not guaranteed to be idempotent.

3. Download images

Results currently contain authenticated Yomi download URLs. Use the actual returned URL, prefix relative paths with https://api.yomiapi.com, and include a valid Bearer Key from the same account. Download after the task succeeds:

curl --fail 'https://api.yomiapi.com/v1/tasks/task_EXAMPLE/artifacts/image-0/content' \
  -H "Authorization: Bearer $YOMI_API_KEY" \
  -D image-headers.txt \
  -o image.bin

Downloads return binary image data. Use the response Content-Type to choose the PNG/JPEG/WebP or other appropriate extension. The response is not HTML or b64_json; encode the downloaded bytes on your server if you need Base64. Never send your Yomi API Key to other domains.

Image links are not guaranteed to remain valid permanently. Download results promptly to your own storage; a webhook does not extend image availability. A normal browser image element cannot attach a Bearer header, so download or proxy the image through your backend.

4. Optional: completion webhook

Add both headers when submitting. Without them, use polling; querying remains available when webhooks are enabled.

X-Async-Callback-URL: https://your-domain.example/image-completed
X-Async-Callback-Secret: YOUR_CALLBACK_SECRET

Use a public HTTPS callback URL on the default port 443. The secret must contain 16–256 printable ASCII characters; a hex-encoded random value of at least 32 bytes is recommended. Do not reuse your Yomi API Key. On completion, a JSON POST is sent to the URL. Notifications for all four families use lowercase statuses. Success example:

{
  "event": "image.task.completed",
  "task_id": "task_EXAMPLE",
  "model": "gpt-image-2.5-flare",
  "status": "success",
  "created_at": 1790200000,
  "started_at": 1790200005,
  "finished_at": 1790200045,
  "result_images": [
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-0/content"
    }
  ]
}

model is the model name used in the submission request. Times are Unix seconds; start or finish times are omitted when unavailable. Failure notifications use status: "failed", include error: "Image generation failed", and omit result_images. Midjourney notifications list all returned images.

Signature verification and replay protection

X-Async-Task-Id: task_EXAMPLE
X-Async-Timestamp: 1790200045
X-Async-Signature: sha256=<64 hex characters>

The signature is sha256= followed by the hex digest of HMAC-SHA256(secret, timestamp + "." + rawBody). rawBody must be the original request bytes, not reserialized JSON. Use a constant-time comparison and validate the timestamp, for example within five minutes. Keep your server clock synchronized. Python example:

import hashlib
import hmac
import time

def verify_callback(raw_body: bytes, timestamp: str,
                    signature: str, secret: str) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
        message = timestamp.encode("ascii") + b"." + raw_body
        expected = "sha256=" + hmac.new(
            secret.encode("ascii"), message, hashlib.sha256
        ).hexdigest()
        return hmac.compare_digest(expected, signature)
    except (ValueError, TypeError, UnicodeError):
        return False

Retries, deduplication, and polling fallback

After verification, deduplicate by task_id, persist the event reliably, and return 2xx promptly. Download images in the background. Acknowledge duplicate notifications with 2xx without repeating business actions. Image downloads still require an API Key.

Connection failures, non-2xx responses, or a 10-second timeout trigger retries: at most five delivery attempts in total, with retry delays of approximately 15/60/300/900 seconds plus scheduling delay. Delivery stops once the task has been complete for more than 24 hours. Retries resend the notification without generating another image.

Even with webhooks, query tasks whose notifications have not arrived. Delivery is not guaranteed to occur exactly once. Webhooks do not contain prices, balances, or Token usage and are not billing receipts.

5. Billing and records

Pricing depends on the selected model, resolution, and the price schedule applicable to your account. Check Model Services or your agreed quote. A Midjourney task usually returns four images but is charged as one task, not four.

Use Task history in the console to view asynchronous task progress and results. Reconcile both synchronous and asynchronous charges in Usage statistics and its detailed record export.