Seedream 5.5 · API

Quick start

Three steps: submit a job, poll it, take the image link. Replace YOUR_API_KEY with your key and the commands below run as they are.

Step 1 · Submit (returns a job id at once, HTTP 202)

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.5", "prompt": "A cafe doorway in an old alley at dusk, a chalkboard reading “Today: Osmanthus Latte $4”, a ginger cat beside it, photorealistic", "size": "16:9", "resolution": "2K"}'

Response (HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedream-5.5"
}

Step 2 · Poll every 2–3 seconds until status is succeeded or failed

curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Response when it succeeds

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedream-5.5",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "seedream-5.5"}
}

Step 3 · data[0].url is the image (the original PNG). It is kept for 7 days; download it to your own storage to keep it longer.

Complete example (Python: submit, wait, save to disk)

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. submit
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "seedream-5.5",
    "prompt": "A cafe doorway in an old alley at dusk, a chalkboard reading “Today: Osmanthus Latte $4”, a ginger cat beside it, photorealistic",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. poll every 3 seconds until it finishes
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. download the image
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedream-5.5.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

Request parameters

The JSON body of POST /v1/images/generations:

Other OpenAI parameters (quality, background, output_format, style and the like) are not supported: they have no effect and do not change the price. Results are always the original PNG, returned as a url; with response_format: "b64_json" the result also carries a base64 copy.

Price

Billed per image by tier only: aspect ratio, text-to-image or image-to-image make no difference. The tier price is held when you submit and refunded in full if the job fails. 1 credit = $0.005.

Aspect ratio, resolution and output size

Put the ratio in size and the tier in resolution. You get the original the model draws at that ratio, at one fixed size per ratio and tier, as listed below; never cropped or resized.

• Only the 9 ratios in the table are supported; any other (5:4, 2:1 ...) returns 400 unsupported_size at submit and nothing is charged. A few native sizes are slightly off the nominal ratio (1K 16:9 is 1424×800): that is the size the model itself draws. Before delivery the ratio, the size and the model named in the C2PA credential are checked; if any of them does not match, the image is not delivered, the job fails and nothing is charged.
• size can also be a pixel size (e.g. 2560x1440): it only sets the ratio (within 1.5% of one of the 9), and you still get the original at that ratio's size in the table. The tier comes from resolution; without it the longest side decides: up to 1600 is 1K, 1601 to 3200 is 2K.
• This model has 1K and 2K only: asking for 4K (resolution: "4K", or a size whose longest side is over 3200) is refused at once with 400 unsupported_resolution, and nothing is charged. For 2K, send resolution: "2K".

Image-to-image and reference images

• Send image (one picture) or images (several, up to 8; any beyond 8 are not used) and the job runs image-to-image; say in the prompt what to change. POST /v1/images/edits takes the same parameters.
• Both endpoints take a JSON body only, not a multipart file upload, so the OpenAI SDK's images.edit() cannot be used as is: pass links or base64 as in the example below.
• Each reference can be a public image URL (http or https), a data: URI or plain base64, up to 16MB each, in a common format such as JPEG, PNG or WebP.
• A URL has to download the image itself: not a web page, and not behind a login or hotlink protection. A reference we cannot read is refused at submit with a 400 that says which one and why; no job is created and nothing is charged.
• For edits and fusions the output ratio follows size (1:1 when absent), not the reference image; to keep the original's ratio, set size to that ratio. You get the model's original, never cropped or resized. To edit over several rounds, pass the previous result as the next round's reference.
• We host the references for you and keep them for 7 days.

Image-to-image with two references

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.5", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Job status and fields

GET /v1/images/jobs/{id} reports these statuses; every field is described in Async jobs. Poll every 2–3 seconds, or use a webhook.

One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and image links for 7 days.

How long it takes

Usually 20–40 seconds from submit to result when the service is not busy; 2K and several references are a little slower. During the Beta, peaks can be slower or fail (failures are not charged).

Errors and refunds

An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under Error codes.

Errors at submit

Failed jobs (status failed)

Webhooks instead of polling

Add callback_url when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. Webhook docs →

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.5", "prompt": "A cafe doorway in an old alley at dusk, a chalkboard reading “Today: Osmanthus Latte $4”, a ginger cat beside it, photorealistic", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'