> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Seedream images
> Use CometAPI POST /v1/images/generations for Seedream image generation with text prompts, reference images, sequential image output, and async tasks.
Use CometAPI's OpenAI-compatible `POST /v1/images/generations` route to run Seedream image generation. This endpoint supports text-to-image prompts, reference-image requests, and bounded sequential image output when the selected model supports those controls.
This page covers `seedream-5-0-pro-260628` for Pro text-to-image requests and `seedream-5-0-260128` for Seedream 5.0 reference-image, sequential, and async examples. For account availability, see the [Models page](/overview/models) or query `/v1/models`. For provider parameter details, see the BytePlus [image generation API](https://docs.byteplus.com/en/docs/ModelArk/1541523) and [Seedream 4.0-5.0 tutorial](https://docs.byteplus.com/en/docs/ModelArk/1824121).
## Choose a request shape
* Text to image: send `model`, `prompt`, `size`, and optional output controls such as `response_format`, `output_format`, and `watermark`.
* Image to image: add `image` as an array of public HTTPS URLs or data URIs. Use an array even when you send one reference image.
* Sequential prompt: set `sequential_image_generation` to `auto` and use `sequential_image_generation_options.max_images` as an upper bound. The model can return fewer images than the maximum.
* Async task: add `async: true` when you want the create request to return `data.task_id` instead of holding the HTTP connection open.
Reference images plus generated images must stay within the provider limit. Keep sequential requests bounded with `max_images`.
## Run an async image task
Set `async` to `true` for image jobs that your client should submit and poll. The create request returns `data.task_id`; use that value with [Retrieve a Seedream image task](/api/image/seededit-seedream/bytedance-image-generation-task) until `data.status` is `success` or `failure`.
Use `2K` in the async examples for Seedream 5.0 requests. Size support varies by model ID, so choose a model-supported size before you submit an async task.
## Send reference images
Use `data:image/png;base64,YOUR_BASE64_IMAGE` for inline image data, or use a public HTTPS URL that the provider can fetch. The API reference examples show the full JSON shape for each request type.
## Read output URLs
The returned `url` is a signed object-storage link and can contain `&`, `%`, and other special characters. Extract the URL from parsed JSON instead of copying a partial terminal line. In shell examples, `jq -r '.data[]?.url'` preserves the full signed URL.
## OpenAPI
````yaml api/openapi/image/seededit-seedream/post-bytedance-image-generation.openapi.json POST /v1/images/generations
openapi: 3.1.0
info:
title: Seedream image generation API
version: 1.0.0
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/v1/images/generations:
post:
summary: Create Seedream images
operationId: bytedance_image_generation
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
Parameters for Seedream image generation. Send JSON for
text-to-image, image-to-image, and sequential prompt requests.
required:
- model
- prompt
properties:
model:
type: string
description: >-
Seedream model ID to use. Query `/v1/models` or open the
[Models page](/overview/models) for available model IDs.
default: seedream-5-0-pro-260628
prompt:
type: string
description: >-
Text prompt describing the image or edit goal. Use a
concrete visual request, such as `a blue ceramic mug on a
white table, soft studio lighting`.
default: >-
A clean product-style render of a blue ceramic mug on a
white table, soft studio lighting.
response_format:
type: string
description: >-
Response image format. Use `url` for a temporary signed
image URL, or `b64_json` when you need base64 image data in
the response.
default: url
enum:
- url
- b64_json
size:
type: string
description: >-
Output resolution. Use a model-supported tier such as `2K`
or a model-supported `WIDTHxHEIGHT` value such as
`2048x2048`. Not every model ID accepts every tier.
default: 2K
image:
type: array
items:
type: string
description: >-
Optional reference images for image-to-image generation.
Each item can be a public HTTPS URL or a data URI such as
`data:image/png;base64,YOUR_BASE64_IMAGE`. Use an array even
for one image. Reference images plus generated images must
not exceed the provider limit.
watermark:
type: boolean
description: >-
When `true`, requests a visible AI-generated watermark on
the output image. Set `false` when your workflow handles
disclosure separately.
default: false
async:
type: boolean
description: >-
CometAPI asynchronous task mode. Set this to `true` to
return immediately with `data.task_id`, then poll the
Seedream image task endpoint `GET
/v1/images/generations/{task_id}` for the final image data.
default: false
output_format:
type: string
description: >-
Output image file format. Use `png` when you need lossless
output, or `jpeg` for smaller files.
default: png
enum:
- png
- jpeg
guidance_scale:
type: number
description: >-
Optional prompt-adherence control for model versions that
support it. Higher values can follow the prompt more closely
but may reduce naturalness. Omit this field when you do not
need model-specific tuning.
minimum: 1
maximum: 10
seed:
type: integer
description: >-
Optional random seed for reproducible attempts on model
versions that support seeding. Use `-1` or omit the field
for a random seed.
minimum: -1
maximum: 2147483647
default: -1
sequential_image_generation:
type: string
description: >-
Controls sequential prompt handling. Use `auto` to let the
model return a sequence when the prompt calls for one. Use
`disabled` for ordinary single-image requests.
default: disabled
enum:
- auto
- disabled
sequential_image_generation_options:
type: object
description: >-
Options for sequential prompt handling. This object is only
used when `sequential_image_generation` is `auto`.
properties:
max_images:
type: integer
description: >-
Maximum number of generated images allowed for the
request. This is an upper bound, not a guarantee that
the model returns that many images.
minimum: 1
maximum: 15
default: 2
default:
model: seedream-5-0-pro-260628
prompt: >-
A clean product-style render of a blue ceramic mug on a white
table, soft studio lighting.
size: 2K
response_format: url
output_format: png
watermark: false
examples:
Text to image (Pro):
summary: Text to image with a Pro Seedream model
value:
model: seedream-5-0-pro-260628
prompt: >-
A clean product-style render of a blue ceramic mug on a
white table, soft studio lighting.
size: 2K
response_format: url
output_format: png
watermark: false
Image to image (5.0):
summary: Use a reference image with Seedream 5.0
value:
model: seedream-5-0-260128
prompt: >-
Transform this product photo into a soft watercolor
illustration while preserving the main object layout.
image:
- data:image/png;base64,YOUR_BASE64_IMAGE
size: 2K
response_format: url
watermark: false
Sequential prompt (5.0):
summary: >-
Allow a sequence when the prompt calls for multiple related
images
value:
model: seedream-5-0-260128
prompt: >-
Create a two-step visual sequence showing a sprout growing
into a small plant, consistent flat illustration style.
size: 2K
response_format: url
sequential_image_generation: auto
sequential_image_generation_options:
max_images: 2
watermark: false
Async image task (5.0):
summary: Submit an async Seedream image task and poll by task ID
value:
model: seedream-5-0-260128
prompt: >-
A small blue origami bird on a white background, clean
product illustration.
size: 2K
response_format: url
async: true
watermark: false
responses:
'200':
description: >-
Image generation response. Synchronous requests return completed
image data. Async requests return a task response with
`data.task_id`.
content:
application/json:
schema:
oneOf:
- type: object
required:
- created
- data
properties:
created:
type: integer
description: >-
Unix timestamp in seconds when the image response was
created.
data:
type: array
description: >-
Generated image results. The array can contain one or
more images depending on the request and model
response.
items:
type: object
properties:
url:
type: string
description: >-
Temporary signed URL for the generated image.
Save or download the image before the URL
expires.
b64_json:
type: string
description: >-
Base64-encoded image data when `response_format`
is `b64_json`.
size:
type: string
description: >-
Pixel dimensions of the generated image when
returned by the model, such as `2048x2048`.
usage:
type: object
description: >-
Usage information for the request. Fields vary by
model and route.
properties:
input_images:
type: integer
description: >-
Number of reference images received by the route,
when reported.
generated_images:
type: integer
description: Number of generated images, when reported.
output_tokens:
type: integer
description: >-
Image output tokens charged for the generated
image data, when reported.
total_tokens:
type: integer
description: Total tokens reported for the request.
- type: object
title: Async task response
required:
- code
- data
properties:
code:
type: string
description: >-
Request status code. A successful async submit returns
`success`.
example: success
message:
type: string
description: Optional status message.
data:
type: object
required:
- task_id
- status
- data
properties:
task_id:
type: string
description: >-
Task ID to pass to `GET
/v1/images/generations/{task_id}`.
status:
type: string
description: Task state for the submitted image generation job.
enum:
- pending
- success
- failure
data:
type: array
description: >-
Empty at submit time. Poll the task endpoint to
receive final image data.
items:
type: object
example:
code: success
message: ''
data:
task_id:
status: pending
data: []
examples:
completed:
summary: Completed image response
value:
created: 1781075000
data:
- url: https:///.png
size: 2048x2048
usage:
generated_images: 1
total_tokens: 0
async_task:
summary: Async task response
value:
code: success
message: ''
data:
task_id:
status: pending
data: []
x-codeSamples:
- lang: Shell
label: Text to image (Pro)
source: |
curl -s https://api.cometapi.com/v1/images/generations \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro-260628",
"prompt": "A clean product-style render of a blue ceramic mug on a white table, soft studio lighting.",
"size": "2K",
"response_format": "url",
"output_format": "png",
"watermark": false
}' | jq -r '.data[]? | .url // .b64_json'
- lang: Python
label: Text to image (Pro)
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/generations",
headers={
"Authorization": "Bearer " + os.environ["COMETAPI_KEY"],
"Content-Type": "application/json",
},
json={"model": "seedream-5-0-pro-260628", "prompt": "A clean product-style render of a blue ceramic mug on a white table, soft studio lighting.", "size": "2K", "response_format": "url", "output_format": "png", "watermark": False},
timeout=180,
)
response.raise_for_status()
result = response.json()
for image in result.get("data", []):
print(image.get("url") or image.get("b64_json"))
- lang: JavaScript
label: Text to image (Pro)
source: >
const response = await
fetch("https://api.cometapi.com/v1/images/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "seedream-5-0-pro-260628",
"prompt": "A clean product-style render of a blue ceramic mug on a white table, soft studio lighting.",
"size": "2K",
"response_format": "url",
"output_format": "png",
"watermark": false
}),
});
if (!response.ok) {
throw new Error(await response.text());
}
const result = await response.json();
for (const image of result.data ?? []) {
console.log(image.url ?? image.b64_json);
}
- lang: Shell
label: Image to image (5.0)
source: |
curl -s https://api.cometapi.com/v1/images/generations \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-260128",
"prompt": "Transform this product photo into a soft watercolor illustration while preserving the main object layout.",
"image": [
"data:image/png;base64,YOUR_BASE64_IMAGE"
],
"size": "2K",
"response_format": "url",
"watermark": false
}' | jq -r '.data[]? | .url // .b64_json'
- lang: Python
label: Image to image (5.0)
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/generations",
headers={
"Authorization": "Bearer " + os.environ["COMETAPI_KEY"],
"Content-Type": "application/json",
},
json={"model": "seedream-5-0-260128", "prompt": "Transform this product photo into a soft watercolor illustration while preserving the main object layout.", "image": ["data:image/png;base64,YOUR_BASE64_IMAGE"], "size": "2K", "response_format": "url", "watermark": False},
timeout=180,
)
response.raise_for_status()
result = response.json()
for image in result.get("data", []):
print(image.get("url") or image.get("b64_json"))
- lang: JavaScript
label: Image to image (5.0)
source: >
const response = await
fetch("https://api.cometapi.com/v1/images/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "seedream-5-0-260128",
"prompt": "Transform this product photo into a soft watercolor illustration while preserving the main object layout.",
"image": [
"data:image/png;base64,YOUR_BASE64_IMAGE"
],
"size": "2K",
"response_format": "url",
"watermark": false
}),
});
if (!response.ok) {
throw new Error(await response.text());
}
const result = await response.json();
for (const image of result.data ?? []) {
console.log(image.url ?? image.b64_json);
}
- lang: Shell
label: Sequential prompt (5.0)
source: |
curl -s https://api.cometapi.com/v1/images/generations \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-260128",
"prompt": "Create a two-step visual sequence showing a sprout growing into a small plant, consistent flat illustration style.",
"size": "2K",
"response_format": "url",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {
"max_images": 2
},
"watermark": false
}' | jq -r '.data[]? | .url // .b64_json'
- lang: Python
label: Sequential prompt (5.0)
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/generations",
headers={
"Authorization": "Bearer " + os.environ["COMETAPI_KEY"],
"Content-Type": "application/json",
},
json={"model": "seedream-5-0-260128", "prompt": "Create a two-step visual sequence showing a sprout growing into a small plant, consistent flat illustration style.", "size": "2K", "response_format": "url", "sequential_image_generation": "auto", "sequential_image_generation_options": {"max_images": 2}, "watermark": False},
timeout=180,
)
response.raise_for_status()
result = response.json()
for image in result.get("data", []):
print(image.get("url") or image.get("b64_json"))
- lang: JavaScript
label: Sequential prompt (5.0)
source: >
const response = await
fetch("https://api.cometapi.com/v1/images/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "seedream-5-0-260128",
"prompt": "Create a two-step visual sequence showing a sprout growing into a small plant, consistent flat illustration style.",
"size": "2K",
"response_format": "url",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {
"max_images": 2
},
"watermark": false
}),
});
if (!response.ok) {
throw new Error(await response.text());
}
const result = await response.json();
for (const image of result.data ?? []) {
console.log(image.url ?? image.b64_json);
}
- lang: Shell
label: Async image task (5.0)
source: |
RESPONSE=$(curl -s https://api.cometapi.com/v1/images/generations \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-260128",
"prompt": "A small blue origami bird on a white background, clean product illustration.",
"size": "2K",
"response_format": "url",
"async": true,
"watermark": false
}')
printf "%s\n" "$RESPONSE" | jq -r '.data.task_id'
- lang: Python
label: Async image task (5.0)
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/generations",
headers={
"Authorization": "Bearer " + os.environ["COMETAPI_KEY"],
"Content-Type": "application/json",
},
json={
"model": "seedream-5-0-260128",
"prompt": "A small blue origami bird on a white background, clean product illustration.",
"size": "2K",
"response_format": "url",
"async": True,
"watermark": False,
},
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result["data"]["task_id"])
- lang: JavaScript
label: Async image task (5.0)
source: >
const response = await
fetch("https://api.cometapi.com/v1/images/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "seedream-5-0-260128",
prompt: "A small blue origami bird on a white background, clean product illustration.",
size: "2K",
response_format: "url",
async: true,
watermark: false,
}),
});
if (!response.ok) {
throw new Error(await response.text());
}
const result = await response.json();
console.log(result.data.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication. Use your CometAPI key.
````