How to Use seedream-5.0-lite Image-to-Image via the hiapi API

This recipe shows you how to call seedream-5.0-lite's image-to-image mode through the hiapi unified task API: the exact request shape, a working curl command, a Python script you can drop into a backend, and the validation gotchas this model enforces that others don't.

By the end you'll have a script that takes one or more reference image URLs plus an edit prompt and returns a generated image URL ready to download.

What you need

• An hiapi account and an API key. Grab one from the hiapi dashboard.
• One or more reference images hosted at public HTTPS URLs. This model accepts up to 14 reference images in a single request, which is what makes it useful for multi-reference workflows — blending a subject from one image with the style or setting of another.
• A text prompt describing the edit or transformation (minimum 3 characters — yes, the API validates that).

All requests go to the unified task endpoint with your key in the Authorization header:

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

The request shape (and what this model requires)

The model id is seedream-5.0-lite/image-to-image — pass it bare, exactly as listed in /v1/models. Its input schema is strict, and all four fields are required:

Field	Type	Notes
prompt	string	The edit instruction. Min length 3.
image_urls	string[]	1–14 reference image URLs.
aspect_ratio	string	One of 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9.
resolution	string	Only 2K or 4K. There is no 1K tier on this model.

Two things trip people up coming from other models on the platform:

1. resolution only accepts 2K or 4K. If you have shared task-submission code that defaults to "1K" (which works on many other image models), this model rejects it with a 400.
2. Extra fields are rejected, not ignored. Sending size, n, or anything outside the schema returns 400 INVALID_REQUEST with additional properties '<field>' not allowed. The task API validates input per model — don't reuse another model's payload blindly.

Minimal working example: curl

Create the task:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Replace the background with a sunlit Tokyo street at golden hour, keep the subject unchanged",
      "image_urls": ["https://your-cdn.example.com/subject.png"],
      "aspect_ratio": "3:2",
      "resolution": "2K"
    }
  }'

A successful submission returns a task id inside data:

{"code": 200, "data": {"taskId": "task_abc123..."}}

Poll for the result:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk-<your-key>"

While running, data.status is pending/processing. On completion it flips to "success" and the image appears in data.output:

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

The output URL is short-lived (note the expireAt). Download the bytes immediately and store them yourself — never hotlink or persist the raw URL.

Multi-reference: passing several images

To blend multiple references — say, a product shot plus a style reference — just add more URLs to image_urls and tell the prompt what each one contributes:

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "Place the product from the first image into the scene from the second image, matching its lighting and color grade",
    "image_urls": [
      "https://your-cdn.example.com/product.png",
      "https://your-cdn.example.com/scene-reference.jpg"
    ],
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}

The hard cap is 14 URLs; a 15th gets you 400 INVALID_REQUEST: image_urls: maxItems: got 15, want 14. In practice 2–4 well-chosen references with a prompt that explicitly assigns each a role ("keep the subject from image 1, take the palette from image 2") gives far more controllable edits than a pile of loosely related images.

For precise, targeted edits on a single image — swap a background, change an outfit, remove an object — use one reference URL and state both what to change and what to keep ("keep the face and pose unchanged"). Seedream models follow preservation instructions well, and being explicit is what separates a surgical edit from a full reinterpretation.

Production-ready Python: submit, poll, download

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Create the task
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,  # this model: "2K" or "4K" only
        },
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. Poll until terminal state
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Download immediately — the URL expires
            img = requests.get(outputs[0]["url"], timeout=120)
            img.raise_for_status()
            return img.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} still running after 600s")


if __name__ == "__main__":
    png = edit_image(
        "Replace the background with a minimalist studio backdrop, keep the subject unchanged",
        ["https://your-cdn.example.com/subject.png"],
        aspect_ratio="3:2",
    )
    with open("edited.png", "wb") as f:
        f.write(png)
    print(f"saved edited.png ({len(png)} bytes)")

Callbacks instead of polling

Polling is fine for scripts and worker queues. For web backends, register a callback when you create the task and let hiapi push the terminal state to you — the callback object sits at the top level of the request, next to model:

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

With "when": "final" you get exactly one POST when the task reaches success or fail. Two rules for the handler:

• Make it idempotent. Key your processing on the task id, so a redelivered webhook doesn't double-process. Store the task id at submission time and treat the callback as "go fetch and finalize", not as the sole source of truth.
• Keep a reconciliation path. If your endpoint was down when the callback fired, a periodic sweep that GETs /v1/tasks/<id> for unresolved ids catches anything missed.

If your callback never seems to arrive, work through why your hiapi task callback isn't firing — it covers the common failure modes in order of likelihood.

Error handling: the three failures that matter

401 permission_denied at creation — your key can't use this model. The body looks like:

{"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "type": "hiapi_error"}}

Check the key's model permissions in the dashboard, or use a key that has image models enabled.

400 INVALID_REQUEST at creation — your input doesn't match this model's schema. The message names every offending field at once (e.g. resolution: value must be one of '2K', '4K'; <root>: additional properties 'size' not allowed), so read it fully and fix all fields in one pass. These are permanent errors — retrying the same payload will fail forever.

status: "fail" on the task — creation succeeded but generation failed (bad reference URL the backend couldn't fetch, content policy, upstream capacity). The task's error.code and error.message say which. Unlike 400s, some of these are transient and worth one retry with backoff.

Also worth knowing: a GET for a nonexistent or expired task id returns 404 task not found — treat that as terminal in reconciliation sweeps, not as "still pending".

Where to go next

• seedream-5.0-lite/image-to-image model page — playground and per-image pricing.
• hiapi pricing — current rates across all image models.
• Best image-to-image APIs in 2026 — how seedream compares to gpt-image-2 and others on the same edit.
• gpt-image-2 image-to-image recipe — same task API, different input schema; a good illustration of why payloads don't transfer between models.
• hiapi docs — full task API reference.

FAQ

How many reference images can I pass to seedream-5.0-lite image-to-image? Up to 14 in the image_urls array. One is the minimum — the field is required, so a pure text-to-image call should use seedream-5.0-lite/text-to-image instead.

Why do I get "value must be one of '2K', '4K'" when 1K works on other models? Input schemas are per-model on the task API. seedream-5.0-lite's image-to-image mode only offers 2K and 4K output; other models expose a 1K tier. Never reuse another model's payload without checking.

Can I send the reference image as base64 instead of a URL? This model's schema takes image_urls — an array of URLs. Host your image at a reachable HTTPS URL (any CDN, object storage bucket, or presigned URL works) and pass that.

How long does a generation take, and how long is the output URL valid? Typically well under the 600-second polling budget in the Python example above. The output URL carries an expireAt timestamp — download the bytes as soon as the task succeeds and store them in your own storage.

Does the same code work for seedream-5.0-lite text-to-image? Same endpoint and flow, but text-to-image has its own input schema (no image_urls). Swap the model id to seedream-5.0-lite/text-to-image and drop the reference images — then verify with a test call, since required fields differ per mode.

What does it cost per image? Pricing is usage-based per generation and varies by resolution. Check the live rates on the pricing page.