Image generation & editing

Generate an image

Send a prompt to POST /v1/images/generations. This example uses gpt-image-2.5 and returns a downloadable image URL.

curl --request POST \
  --url https://api.sukidata.com/v1/images/generations \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: image-example-001' \
  --data '{
    "model": "gpt-image-2.5",
    "prompt": "A blue ceramic cup on a plain white background",
    "response_format": "url"
  }'

{
  "created": 1788739200,
  "data": [{ "url": "https://example.com/result.png" }]
}

Read the result from data[0].url. Omit response_format to receive Base64 in data[0].b64_json instead.

Requests require an API key and sufficient AI balance. Use a new Idempotency-Key for each task; reuse it for retries.

Edit an image

Send an image and a prompt describing your changes to POST /v1/images/edits.

Upload a file

curl --request POST \
  --url https://api.sukidata.com/v1/images/edits \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Idempotency-Key: image-edit-example-001' \
  --form 'model=gpt-image-2.5' \
  --form 'prompt=Change the cup to green, keeping the composition' \
  --form 'image=@input.png'

For multiple images, repeat --form 'image[]=@file.png' with each file. Inputs can be PNG, JPEG or WebP.

Use an image URL

curl --request POST \
  --url https://api.sukidata.com/v1/images/edits \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: image-json-edit-example-001' \
  --data '{
    "model": "gpt-image-2.5",
    "prompt": "Replace the background with a snowy mountain",
    "image": {"image_url": "https://example.com/input.png"},
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "webp"
  }'

Use public HTTPS image URLs or Base64 data URLs. Choose one JSON field, image or images; either accepts a single reference or an array.

The optional mask must be a PNG with an alpha channel and the same dimensions as the first image. Transparent areas identify where to edit.

The request body can be up to 48 MiB. The selected model determines the maximum number of reference images.

Adjust the output

Find available models with GET /v1/models. See the API reference for all fields and the pricing guide for size bands and 1K presets.

Generate in the background

Use POST /v1/images/generations/async to receive a task ID immediately after submission. For edits, use POST /v1/images/edits/async. Both accept the same parameters as their synchronous counterparts.

curl --request POST \
  --url https://api.sukidata.com/v1/images/generations/async \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: image-async-example-001' \
  --data '{"model":"gpt-image-2.5","prompt":"A blue ceramic cup"}'

{
  "id": "img_example",
  "object": "image.task",
  "status": "queued"
}

curl https://api.sukidata.com/v1/images/tasks/img_example \
  --header "Authorization: Bearer $SUKIDATA_API_KEY"

The submission response also provides the task URL in the Location header. Queries require an API key from the same Workspace.

Python example

With the OpenAI Python SDK installed, set your Sukidata key and API base URL:

import os
import uuid
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUKIDATA_API_KEY"],
    base_url="https://api.sukidata.com/v1",
    timeout=120.0,
    max_retries=2,
)

request_key = str(uuid.uuid4())
result = client.images.generate(
    model="gpt-image-2.5",
    prompt="A blue ceramic cup on a plain white background",
    extra_headers={"Idempotency-Key": request_key},
)
image_base64 = result.data[0].b64_json

Find and save results

GET /v1/images/tasks lists your Workspace's tasks. Filter by model, status or prompt text, then use GET /v1/images/tasks/{task_id} to view a task's prompt, parameters, images and charge.

Image URLs are available for 31 days from publication. Save the files before url_expires_at; expired images cannot be downloaded through the API. Anyone with a URL can open that image, so share links only when intended.

Errors and retries

A timeout or closed connection does not cancel a task. If the response includes X-Sukidata-Task-ID, query that task before submitting again.

If no task ID was received, retry with the same Idempotency-Key, parameters and files. Changing the key creates a new task that can incur another charge. Interrupted input uploads can be retried for ten minutes after task creation.

• 400: check the model, input files and parameter values.
• 402: add funds to your AI balance.
• 409: the idempotency key was already used with different parameters or files.
• 410: the upload retry window or image link has expired.
• 502 / 503: check the existing task first; it may still be processing.

For other errors, check error.code and error.message in the response. Include the task ID or X-Request-ID when contacting support.