ByteDance

Seedream 5.0

seedream-5.0-lite/image-to-image

ByteDance's production-grade image generation model, supporting web retrieval and multi-step logical reasoning, 4K output, and example-based editing, suitable for product images and infographic creation

seedream-5.0-flash seedream-5.0-lite/image-to-image seedream-5.0-lite/text-to-image seedream-5.0-pro/image-to-image seedream-5.0-pro/text-to-image

Try seedream-5.0-lite/image-to-image

Input

Output

image

Fill in the parameters and run — results show up here.

Pricing

seedream-5.0-lite/image-to-image per image

Unit Price	$0.035

Positioning Overview

The image-to-image route of Seedream 5.0 Lite accepts 1 to 14 reference images, modifies or blends images according to prompts, and outputs finished images at 2K or 4K. It is suitable for developers who need to create derivative works based on existing assets and unify visual styles, for example, adjusting aspect ratios, redrawing details, or compositing elements from multiple images on the basis of existing product images or character images. Called through the unified HiAPI.ai interface, its input and output structures are fixed, making it easy to integrate into batch processing workflows.

Key Highlights

Supports simultaneous input of up to 14 reference images — multiple assets can be handed to the model at once for blending or reference, reducing the cost of multiple rounds of calls and stitching.
Two resolution tiers, 2K and 4K, with consistent billing — billed per image; the resolution tier does not affect billing, so you can freely choose the output specification according to delivery precision.
Covers eight common aspect ratios — from 1:1 to 21:9, all can be specified directly, adapting to different placements such as e-commerce main images, vertical assets, and wide banners.

Capability Description

Multi-image reference editing: Provide URLs of 1 to 14 reference images, and the model modifies or combines the images according to the prompt, suitable for iterating on existing assets rather than generating from scratch.

Controllable resolution and aspect ratio: Output can be selected as 2K or 4K, and images are generated in eight ratios including 1:1, 16:9, and 9:16, reducing post-processing cropping.

Long-instruction editing: Prompts support up to 3000 characters, accommodating fairly complete descriptions of editing requirements, making it easy to explain complex changes in one go.

Applicable Scenarios

E-commerce operations: changing placements and aspect ratios for existing product images — upload original product images and specify a ratio for redrawing, producing main images ready for listing or horizontal/vertical ad assets.
Design teams: compositing multi-element assets — input multiple reference images and merge them into one finished piece, for quick assembly of campaign posters or visual drafts.
Content teams: secondary editing of series visual assets — adjust the image based on existing character or style images, producing a series of illustrations with a consistent style.

Limitations and Selection Advice

Only image-to-image is supported, and at least one reference image must be provided; pure text-to-image is not possible, so such needs should choose the text-to-image route in the same family. Only two resolution tiers, 2K and 4K, are available, and aspect ratios are limited to the eight enumerated ratios; custom sizes are not supported. Prompts must be between 4 and 3000 characters, and reference images support JPEG, PNG, and WebP, with each image no larger than 10MB. For scenarios requiring higher-specification text rendering or fine local editing, consider the Pro route in the same family.

What's new

View changelog →

New model seedream-5.0-pro/image-to-image Now Available Nov 3, 2026
New model New model launched: seedream-5.0-pro/text-to-image Nov 3, 2026
New model seedream-5.0-lite/image-to-image model now available Nov 3, 2026

Create a generation task

POST https://api.hiapi.ai/v1/tasks

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: seedream-5.0-lite/image-to-image

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for seedream-5.0-lite/image-to-image and route default — see the parameter table below.

promptstringRequiredminLength 4maxLength 3000

Edit instruction describing how to modify or combine the reference images.

image_urlsarrayRequiredminItems 1maxItems 14

Array of image URLs for editing or reference, supporting 1-14 images in JPEG/PNG/WebP format, up to 10MB each.

Array [ string ]

resolutionstringRequiredDefault: "2K"

Output image resolution tier: 2K for standard quality, 4K for maximum detail; both tiers are priced the same. Default is 2K.

Options:2K4K

aspect_ratiostringRequiredDefault: "1:1"

Aspect ratio of the output image. Default is 1:1.

Options:1:14:33:416:99:162:33:221:9

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "…",
    "image_urls": "…",
    "resolution": "2K",
    "aspect_ratio": "1:1"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedream-5.0-lite/image-to-image",
    input: {
      "prompt": "…",
      "image_urls": "…",
      "resolution": "2K",
      "aspect_ratio": "1:1"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
          "prompt": "…",
          "image_urls": "…",
          "resolution": "2K",
          "aspect_ratio": "1:1"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}