How to use seedream-5.0-pro/image-to-image via the hiapi API: curl, Python, and a working request

Seedream 5.0 Pro is ByteDance's flagship image model, and its image-to-image endpoint takes one or more reference images plus a text instruction and returns an edited result — restyles, background swaps, product cleanups, multi-image composites. On hiapi it runs on the unified async tasks API: you create a task, poll it (or receive a callback), then download the output. Every parameter, enum value, and error message below was verified against the live API before this guide was published.

What you'll build and what you need

Goal: send a reference image and an edit instruction to seedream-5.0-pro/image-to-image, get back the edited image, and save it locally.

You need two things:

1. A hiapi API key — grab one from your dashboard. It goes in the Authorization: Bearer sk-... header.
2. Publicly reachable image URLs — the API fetches your reference images server-side, so they must be accessible over HTTPS. Presigned URLs from your own bucket work fine; localhost or private paths do not. If a URL can't be fetched you'll get a normalization error, not a silent failure.

Parameters (verified)

The model id is seedream-5.0-pro/image-to-image, exactly as returned by GET /v1/models. All four input fields are required:

Field	Type	Required	Values / notes
prompt	string	yes	The edit instruction.
image_urls	array of strings	yes	1–10 publicly reachable image URLs. Always an array, even for a single image.
aspect_ratio	string	yes	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	yes	1K or 2K

Two things that trip people up:

• The schema is strict. Unknown fields are rejected — sending n, size, or seed returns a 400 with additional properties ... not allowed. Input schemas differ per model on hiapi (some models use size, some use aspect_ratio), so don't copy fields across model families.
• resolution here is 1K/2K only. Other seedream endpoints accept different resolution sets, so this is worth double-checking per endpoint rather than assuming.

Minimal working example: curl

Create the task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

A successful create returns the task id at data.taskId (response abbreviated):

{ "data": { "taskId": "<your-task-id>" } }

Poll it until it reaches a terminal state:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status ends at either success — your image URL is at data.output[0].url — or fail, with details in data.error.code and data.error.message.

Full Python script: create, poll, download

Standard library only — nothing to install:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

Production notes

Prefer a callback over polling on servers. Add a top-level callback object when you create the task and hiapi will POST to your endpoint once, at the terminal state:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

In your handler, treat the callback as a signal, not a source of truth: take the task id from it, then re-fetch GET /v1/tasks/<id> yourself before acting on it. Polling is still the right call for scripts, notebooks, and one-offs — just keep the interval around 5 seconds.

Make retries idempotent. Store your own mapping of source image → taskId when you create a task. If your process dies mid-poll, re-attach to the stored taskId instead of re-submitting the edit — a re-submit is a second billable task.

Download outputs immediately. The URL at data.output[0].url is time-limited (it carries an expiry). Download the bytes and store them in your own bucket; never hotlink a task output URL in anything user-facing.

Errors you'll actually see:

• 401 with permission_denied — missing or malformed API key. Check the header is exactly Authorization: Bearer sk-....
• 400 with INVALID_REQUEST — input schema violations. The messages are precise, e.g. resolution: value must be one of '1K', '2K' or image_urls: maxItems: got 11, want 10.
• image_urls must be an array — you passed a bare string. Wrap it in a list even for one image.

Where to go next

• Model page: seedream-5.0-pro/image-to-image — capabilities and current status.
• Prices per image are listed on the pricing page.
• Cheaper edits for high-volume pipelines: How to use seedream-5.0-lite image-to-image.
• Choosing between models: Best image-to-image APIs in 2026 compares the same edit across three models.
• Full API reference: hiapi docs.

FAQ

How many reference images can I send? Up to 10 URLs in image_urls. The limit is enforced server-side — 11 images returns maxItems: got 11, want 10.

Can the output keep my input image's aspect ratio? Yes — set aspect_ratio to match_input_image. That's usually what you want for edits and restyles; pick an explicit ratio like 16:9 only when you're deliberately reframing.

Does seedream-5.0-pro image-to-image support 4K? No. This endpoint accepts 1K and 2K only. If you request anything else you'll get a 400 listing the allowed values.

Do my image URLs have to be public? They must be fetchable by hiapi's servers over HTTPS. Presigned URLs (S3, R2, GCS) work well and let you keep the bucket itself private.

What does seedream-5.0-pro image-to-image cost per image? Pricing is per successful image and varies by resolution — check the live pricing page for current rates.

How is this different from seedream-5.0-lite image-to-image? Pro is the flagship tier aimed at harder, higher-fidelity edits; lite is the faster, cheaper option for volume work. The request shape is similar, so the cleanest way to decide is to run the same edit through both — start from the lite guide and compare results against your own references.