HAI Gateway Docs

Volcengine

Seedream Image Generation

Generate images with Volcengine Ark doubao-seedream models. Supports text-to-image, image-to-image, multi-reference fusion, sequential groups, and streaming. Returns image URLs or base64.

POSTv3/images/generations

This is a first-class Volcengine relay channel (on par with /openai, /anthropic, /google). Text-to-image, image-to-image, multi-reference fusion, sequential groups (sequential_image_generation), and streaming (stream) all share this single route — modes are selected entirely by request-body parameters.

Authorizations

Authorizationstringheaderrequired

Use the following format for authentication: Bearer sk-pat-YourAccessToken

The key value is your HAI Gateway Personal Access Token (starting with sk-pat-). No separate Volcengine ARK API Key is required.

Base URL

https://api.hai.network/volcengine

The paths v3/images/generations and api/v3/images/generations are equivalent — either works. This channel does not expose a model-list endpoint (no GET /models); call it directly with a model ID enabled / configured on your account.

Body Parameters

modelstringbodyrequired

A Seedream image model, e.g. doubao-seedream-4-0-250828. Currently covers the 4.0 / 4.5 / 5.0-lite series; the exact callable model ID depends on what is enabled / configured on your HAI Gateway account.

promptstringbodyrequired

Text description of the image

imagestring | string[]body

Reference image(s) for image-to-image / multi-reference fusion. Accepts an image URL or base64 data (data:image/...;base64,...). A single value is image-to-image; an array is multi-reference fusion

sizestringbody

Output resolution. Accepts presets 1K / 2K / 4K, or an explicit pixel size such as 2048x2048. Default 2K

seedintegerbody

Random seed for reproducible results, default -1 (random)

sequential_image_generationstringbody

Group mode: disabled (default, single image) / auto (the model decides whether to produce a related set of images)

sequential_image_generation_optionsobjectbody

Group options, only effective when sequential_image_generation is auto. { "max_images": <integer> } caps the number of images generated in this call

streambooleanbody

Whether to enable streaming (images pushed one by one via SSE), default false. Commonly paired with group mode

response_formatstringbody

Return format: url (default) / b64_json. A url is a temporary link valid for 24 hours — save it promptly

watermarkbooleanbody

Whether to add an "AI generated" watermark, default true. Set to false to disable

toolsarraybody

Tool list. Pass [{ "type": "web_search" }] to enable web-search augmentation; when used, the response usage.tool_usage.web_search returns the actual number of web searches performed

Compatibility with the OpenAI Images API

The request structure aligns with the OpenAI Images API (model / prompt / size / response_format), so basic text-to-image works by pointing the official OpenAI SDK's images.generate() at this endpoint. However, Seedream's differentiators — 2K / 4K resolution, watermark, image for image-to-image / multi-reference fusion, sequential_image_generation groups, stream, and tools web search — are Volcengine extensions beyond the OpenAI contract and must be called with the parameters documented here.

For full parameter descriptions, refer to the Volcengine Ark Image Generation API documentation.

cURL
cURL:Default
curl https://api.hai.network/volcengine/v3/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-pat-YourAccessToken" \
  -d '{
    "model": "doubao-seedream-4-0-250828",
    "prompt": "A Shiba Inu running across a meadow, cinematic, soft light",
    "size": "2K",
    "response_format": "url"
  }'
200
200:Default
{
  "model": "doubao-seedream-4-0-250828",
  "created": 1717400000,
  "data": [
    {
      "url": "https://ark-content-generation.../image.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1
  }
}