Seedream image generation

curl --request POST \
  --url https://api.example.com/v1/images/generations \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "prompt": "<string>",
  "image": {},
  "layer_decomposition": true,
  "size": "<string>",
  "optimize_prompt_options": {
    "mode": "<string>"
  },
  "output_format": "<string>",
  "background": "<string>",
  "output_compression": 123,
  "response_format": "<string>",
  "sequential_image_generation": "<string>",
  "sequential_image_generation_options": {
    "max_images": 123
  },
  "stream": true,
  "watermark": true
}
'

import requests

url = "https://api.example.com/v1/images/generations"

payload = {
    "model": "<string>",
    "prompt": "<string>",
    "image": {},
    "layer_decomposition": True,
    "size": "<string>",
    "optimize_prompt_options": { "mode": "<string>" },
    "output_format": "<string>",
    "background": "<string>",
    "output_compression": 123,
    "response_format": "<string>",
    "sequential_image_generation": "<string>",
    "sequential_image_generation_options": { "max_images": 123 },
    "stream": True,
    "watermark": True
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    prompt: '<string>',
    image: {},
    layer_decomposition: true,
    size: '<string>',
    optimize_prompt_options: {mode: '<string>'},
    output_format: '<string>',
    background: '<string>',
    output_compression: 123,
    response_format: '<string>',
    sequential_image_generation: '<string>',
    sequential_image_generation_options: {max_images: 123},
    stream: true,
    watermark: true
  })
};

fetch('https://api.example.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'prompt' => '<string>',
    'image' => [
        
    ],
    'layer_decomposition' => true,
    'size' => '<string>',
    'optimize_prompt_options' => [
        'mode' => '<string>'
    ],
    'output_format' => '<string>',
    'background' => '<string>',
    'output_compression' => 123,
    'response_format' => '<string>',
    'sequential_image_generation' => '<string>',
    'sequential_image_generation_options' => [
        'max_images' => 123
    ],
    'stream' => true,
    'watermark' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"image\": {},\n  \"layer_decomposition\": true,\n  \"size\": \"<string>\",\n  \"optimize_prompt_options\": {\n    \"mode\": \"<string>\"\n  },\n  \"output_format\": \"<string>\",\n  \"background\": \"<string>\",\n  \"output_compression\": 123,\n  \"response_format\": \"<string>\",\n  \"sequential_image_generation\": \"<string>\",\n  \"sequential_image_generation_options\": {\n    \"max_images\": 123\n  },\n  \"stream\": true,\n  \"watermark\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/images/generations")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"image\": {},\n  \"layer_decomposition\": true,\n  \"size\": \"<string>\",\n  \"optimize_prompt_options\": {\n    \"mode\": \"<string>\"\n  },\n  \"output_format\": \"<string>\",\n  \"background\": \"<string>\",\n  \"output_compression\": 123,\n  \"response_format\": \"<string>\",\n  \"sequential_image_generation\": \"<string>\",\n  \"sequential_image_generation_options\": {\n    \"max_images\": 123\n  },\n  \"stream\": true,\n  \"watermark\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"image\": {},\n  \"layer_decomposition\": true,\n  \"size\": \"<string>\",\n  \"optimize_prompt_options\": {\n    \"mode\": \"<string>\"\n  },\n  \"output_format\": \"<string>\",\n  \"background\": \"<string>\",\n  \"output_compression\": 123,\n  \"response_format\": \"<string>\",\n  \"sequential_image_generation\": \"<string>\",\n  \"sequential_image_generation_options\": {\n    \"max_images\": 123\n  },\n  \"stream\": true,\n  \"watermark\": true\n}"

response = http.request(request)
puts response.read_body

{
  "created": 123,
  "model": "<string>",
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>",
      "output_format": "<string>",
      "z_index": 123,
      "name": "<string>",
      "bounding_box": {
        "absolute": [
          123
        ],
        "normalized": [
          123
        ]
      },
      "url": "<string>",
      "size": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>",
        "type": "<string>",
        "param": "<string>"
      },
      "description": "<string>"
    }
  ],
  "usage": {
    "output_tokens": 123,
    "total_tokens": 123,
    "generated_images": 123,
    "input_images": 123
  }
}

POST

images

generations

Seedream image generation

curl --request POST \
  --url https://api.example.com/v1/images/generations \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "prompt": "<string>",
  "image": {},
  "layer_decomposition": true,
  "size": "<string>",
  "optimize_prompt_options": {
    "mode": "<string>"
  },
  "output_format": "<string>",
  "background": "<string>",
  "output_compression": 123,
  "response_format": "<string>",
  "sequential_image_generation": "<string>",
  "sequential_image_generation_options": {
    "max_images": 123
  },
  "stream": true,
  "watermark": true
}
'

import requests

url = "https://api.example.com/v1/images/generations"

payload = {
    "model": "<string>",
    "prompt": "<string>",
    "image": {},
    "layer_decomposition": True,
    "size": "<string>",
    "optimize_prompt_options": { "mode": "<string>" },
    "output_format": "<string>",
    "background": "<string>",
    "output_compression": 123,
    "response_format": "<string>",
    "sequential_image_generation": "<string>",
    "sequential_image_generation_options": { "max_images": 123 },
    "stream": True,
    "watermark": True
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    prompt: '<string>',
    image: {},
    layer_decomposition: true,
    size: '<string>',
    optimize_prompt_options: {mode: '<string>'},
    output_format: '<string>',
    background: '<string>',
    output_compression: 123,
    response_format: '<string>',
    sequential_image_generation: '<string>',
    sequential_image_generation_options: {max_images: 123},
    stream: true,
    watermark: true
  })
};

fetch('https://api.example.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'prompt' => '<string>',
    'image' => [
        
    ],
    'layer_decomposition' => true,
    'size' => '<string>',
    'optimize_prompt_options' => [
        'mode' => '<string>'
    ],
    'output_format' => '<string>',
    'background' => '<string>',
    'output_compression' => 123,
    'response_format' => '<string>',
    'sequential_image_generation' => '<string>',
    'sequential_image_generation_options' => [
        'max_images' => 123
    ],
    'stream' => true,
    'watermark' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"image\": {},\n  \"layer_decomposition\": true,\n  \"size\": \"<string>\",\n  \"optimize_prompt_options\": {\n    \"mode\": \"<string>\"\n  },\n  \"output_format\": \"<string>\",\n  \"background\": \"<string>\",\n  \"output_compression\": 123,\n  \"response_format\": \"<string>\",\n  \"sequential_image_generation\": \"<string>\",\n  \"sequential_image_generation_options\": {\n    \"max_images\": 123\n  },\n  \"stream\": true,\n  \"watermark\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/images/generations")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"image\": {},\n  \"layer_decomposition\": true,\n  \"size\": \"<string>\",\n  \"optimize_prompt_options\": {\n    \"mode\": \"<string>\"\n  },\n  \"output_format\": \"<string>\",\n  \"background\": \"<string>\",\n  \"output_compression\": 123,\n  \"response_format\": \"<string>\",\n  \"sequential_image_generation\": \"<string>\",\n  \"sequential_image_generation_options\": {\n    \"max_images\": 123\n  },\n  \"stream\": true,\n  \"watermark\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"image\": {},\n  \"layer_decomposition\": true,\n  \"size\": \"<string>\",\n  \"optimize_prompt_options\": {\n    \"mode\": \"<string>\"\n  },\n  \"output_format\": \"<string>\",\n  \"background\": \"<string>\",\n  \"output_compression\": 123,\n  \"response_format\": \"<string>\",\n  \"sequential_image_generation\": \"<string>\",\n  \"sequential_image_generation_options\": {\n    \"max_images\": 123\n  },\n  \"stream\": true,\n  \"watermark\": true\n}"

response = http.request(request)
puts response.read_body

{
  "created": 123,
  "model": "<string>",
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>",
      "output_format": "<string>",
      "z_index": 123,
      "name": "<string>",
      "bounding_box": {
        "absolute": [
          123
        ],
        "normalized": [
          123
        ]
      },
      "url": "<string>",
      "size": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>",
        "type": "<string>",
        "param": "<string>"
      },
      "description": "<string>"
    }
  ],
  "usage": {
    "output_tokens": 123,
    "total_tokens": 123,
    "generated_images": 123,
    "input_images": 123
  }
}

This endpoint is consistent with the official Seedream protocol. It extends the OpenAI Images protocol with Seedream-specific parameters, supporting reference image input, sequential image generation, and layer decomposition.

Features

Compatible with the base parameters of the OpenAI Images protocol (prompt, size, output_format, and more)
Supports image-to-image generation by passing a reference image via image (URL or Base64)
Supports sequential image generation via sequential_image_generation, producing a set of related images from your input, with a configurable maximum count
Supports layer decomposition via layer_decomposition, returning decomposed layers with bounding box information
Supports prompt optimization via optimize_prompt_options (standard / fast modes)
Supports both resolution tiers such as 1K and 2K and explicit sizes such as 1024x1024
Supports watermark control via watermark

Authentication

Include the Authorization header in the format Bearer YOUR_API_KEY.

Supported image models

Models in the seedream series.

Quick example

import requests

url = "https://api.hairoute.ai/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "dola-seedream-5.0-pro",
    "prompt": "An orange cat wearing an astronaut helmet floating in space with Earth in the background",
    "size": "2K",
    "watermark": False,
    "response_format": "url"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const response = await fetch('https://api.hairoute.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'dola-seedream-5.0-pro',
    prompt: 'An orange cat wearing an astronaut helmet floating in space with Earth in the background',
    size: '2K',
    watermark: false,
    response_format: 'url'
  })
});

const data = await response.json();
console.log(data);

curl -X POST 'https://api.hairoute.ai/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "dola-seedream-5.0-pro",
    "prompt": "An orange cat wearing an astronaut helmet floating in space with Earth in the background",
    "size": "2K",
    "watermark": false,
    "response_format": "url"
  }'

A successful generation returns the image data:

{
  "created": 1787875200,
  "model": "dola-seedream-5.0-pro",
  "data": [
    {
      "url": "https://example.com/images/generated-1.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "output_tokens": 8320,
    "total_tokens": 8320,
    "generated_images": 1,
    "input_images": 0
  }
}

Next steps

See OpenAI image generation for the base protocol parameters
See OpenAI image edit to edit existing images
See the model list for available image models

Headers

Authorization

string

required

API Key token (Bearer sk-xxx)

Content-Type

string

Body

application/json

model

string

required

Model name

prompt

string

required

Text prompt

image

object

Reference image, URL or Base64 string (Seedream extension parameter, used for image-to-image)

layer_decomposition

boolean

Whether to decompose layers: true to decompose, false not to (default)

size

string

Image size, e.g. "1024x1024", "1K", "2K"

optimize_prompt_options

object

Prompt optimization options

Show child attributes

output_format

string

Output image format, e.g. "png", "jpeg", "webp"

background

string

Background of the generated image: "transparent" / "opaque" / "auto"; defaults to "auto"

output_compression

integer

Output compression level

response_format

string

Response format, "url" or "b64_json"

sequential_image_generation

string

Controls whether to disable sequential image generation (sequential images: a set of related images generated from your input). "auto"/"disabled"; defaults to "disabled"

sequential_image_generation_options

object

Sequential image generation configuration. Only effective when sequential_image_generation is auto.

Show child attributes

stream

boolean

Whether to use streaming (SSE) responses

watermark

boolean

Whether to add a watermark

Response

200 - application/json

created

integer<int64>

Image generation timestamp (Unix seconds)

model

string

Model used

data

object[]

Generated image data list

Show child attributes

usage

object

Token and image usage statistics

Show child attributes

Quick start

API documentation

AI tool integration

Other

Seedream image generation

Features

Authentication

Supported image models

Quick example

Next steps

Headers

Body

Response

​Features

​Authentication

​Supported image models

​Quick example

​Next steps

Headers

Body

Response

Features

Authentication

Supported image models

Quick example

Next steps