ByteDance: Seedream 4.0 (Image to Image) API Reference

About

ByteDance Seedream 4.0 generates a single image from a text prompt and up to 14 reference images through BytePlus ModelArk. This Image to Image endpoint supports 1K, 2K, 4K size presets and custom pixel dimensions within the model limits, with optional watermark control. Generation is exposed through asynchronous platform tasks.

1. Calling the API

Setup your API Key

To begin using Infron, you first need to create an account and generate your API Key.

Once you have your API key, set it as an environment variable in your runtime environment. This allows your applications to securely access Infron’s API.

export INFRON_KEY="YOUR_API_KEY"

Submit a request

For long-running requests, you can poll for results.

curl https://media.onerouter.pro/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "bytedance/seedream-4.0/image-to-image",
  "prompt": "Preserve the main subject in the reference image and change the background to soft blue.",
  "image_urls": [
    "https://arkdocs-en.tos-ap-southeast-1.volces.com/images/image-generation/seedream4_imagesToimages_1.png"
  ]
}'

Response with queue task id

The response will look like this:

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "TASK_ID",
    "object": "image",
    "model": "bytedance/seedream-4.0/image-to-image",
    "status": "created",
    "urls": {
      "query": "https://media.onerouter.pro/v1/images/tasks/TASK_ID"
    },
    "created_at": "YYYY-MM-DD HH:MM:SS"
  }
}

Fetch request status

You can fetch the status of a request to check if it is completed or still in progress.

curl https://media.onerouter.pro/v1/images/tasks/{task_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response with queue task status query

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "TASK_ID",
    "object": "image",
    "model": "bytedance/seedream-4.0/image-to-image",
    "status": "in_progress",
    "fail_reason": "",
    "submit_time": 0,
    "start_time": 0,
    "finish_time": 0,
    "outputs": [],
    "created_at": "YYYY-MM-DD HH:MM:SS"
  }
}

Possible statuses:

created
in_progress
queued
completed
failed

created -> in_progress → queued → completed | failed

Poll every 1-2 seconds until status is "completed" or "failed"

Get the result (when status is "completed")

Once the request is completed, you can fetch the result. See the Output Schema for the expected result format.

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "TASK_ID",
    "object": "image",
    "model": "bytedance/seedream-4.0/image-to-image",
    "status": "completed",
    "fail_reason": "",
    "submit_time": 0,
    "start_time": 0,
    "finish_time": 0,
    "outputs": [
      "OUTPUT_IMAGE_URL"
    ],
    "usage": {
      "image_count": 1
    },
    "cost": {
      "total_cost": 0.03
    },
    "created_at": "YYYY-MM-DD HH:MM:SS"
  }
}

2. Schema

Input

Parameter	Type	Required	Default	Range	Description
`model`	string	Yes	--	`bytedance/seedream-4.0/image-to-image`	Public model ID.
`prompt`	string	Yes	--	--	Text prompt describing the requested single image.
`image_urls`	array	Yes	--	1–14	Ordered, publicly accessible reference image URLs.
`size`	string	No	Upstream default: 2048x2048	`1K`, `2K`, `4K`, `WIDTHxHEIGHT`	Custom area 921,600–16,777,216 pixels; width/height ratio 1:16–16:1.
`n`	integer	No	`1`	`1`	This endpoint returns a single output image.
`watermark`	boolean	No	`false`	`true`, `false`	Add or omit the upstream AI-generated watermark.
`provider`	object	No	--	Platform routing options	Select the provider and service tier.
`queue`	boolean	No	`true`	Platform-managed	Generation uses an asynchronous platform task.
`webhook_url`	string	No	--	Callback URL	Optional existing task completion callback.

Only single-image output is exposed. Sequential generation, prompt-optimization modes and streaming are not enabled on this platform endpoint. Unsupported fields are filtered before the BytePlus request.

Example request

curl https://media.onerouter.pro/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "bytedance/seedream-4.0/image-to-image",
  "prompt": "Preserve the main subject in the reference image and change the background to soft blue.",
  "image_urls": [
    "https://arkdocs-en.tos-ap-southeast-1.volces.com/images/image-generation/seedream4_imagesToimages_1.png"
  ],
  "size": "4K",
  "n": 1,
  "watermark": true
}'

Output

Parameter	Type	Range	Description
code	integer	--	Status code of the request.
message	string	--	Status message of the request.
data	object	--	Data of the task.
data.task_id	string	--	ID of the task.
data.object	string	--	Object type of the task.
data.model	string	--	Model name of the task.
data.status	string	`created`, `in_progress`, `queued`, `completed`, `failed`	Status of the task.
data.fail_reason	string	--	Fail reason of the task.
data.submit_time	integer	--	Timestamp of the task submission.
data.start_time	integer	--	Timestamp of the task start.
data.finish_time	integer	--	Timestamp of the task finish.
data.outputs	array	--	Outputs of the task.
data.created_at	string	--	Timestamp of the task creation.

Example output

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "TASK_ID",
    "object": "image",
    "model": "bytedance/seedream-4.0/image-to-image",
    "status": "completed",
    "fail_reason": "",
    "submit_time": 0,
    "start_time": 0,
    "finish_time": 0,
    "outputs": [
      "OUTPUT_IMAGE_URL"
    ],
    "usage": {
      "image_count": 1
    },
    "cost": {
      "total_cost": 0.03
    },
    "created_at": "YYYY-MM-DD HH:MM:SS"
  }
}

3. Detailed Pricing

Generation Type	Output Images	Estimated Price
Image to Image	1	$0.03
Multi-reference Image to Image	1	$0.03

Input reference images are free. Prices are in USD per successfully generated output image.