Seedream

Official API reference: Image generation API (Volcengine Ark). Every field on this page is checked against it; gateway-specific behaviour is collected in "Differences from the official API" at the end.

Models and tiers

• The models above share the same inbound POST /api/v3/images/generations, support text to image and image to image (single / multiple references), and require model and prompt. Sequential sets (sequential_image_generation: "auto") are supported on 5.0 lite / 5.0 / 4.5 / 4.0.
• doubao-seedream-5.0 is an alias of doubao-seedream-5.0-lite: Ark has no standalone 5.0 model, so the two share tiers and price.
• The supported tiers differ by model; the table above lists only common values. See the official Ark documentation for the full range. A tier outside it is refused at creation (HTTP 400) — nothing is rendered, nothing is charged.
• On 5.0 pro, 1.5K is priced the same as 1K (Ark pricing) and is served by only part of the supplier pool, so fewer lanes are available than for the other tiers.
• Which models are reachable on which entry point is decided by the model's protocol list. doubao-seedream-4.0 is served on both the Ark native entry point (this page) and the OpenAI-compatible one (POST /v1/images/generations, see "OpenAI-compatible entry point" below); 5.0 / 5.0 lite / 5.0 pro are served through the OpenAI-compatible image API only (see Image generation (OpenAI-compatible)). Calling an entry point the model does not offer returns 400 model_protocol_not_offered.

The ModelGo gateway accepts Seedream requests on the official Volcengine Ark Images API path with the official request/response shapes unchanged; the gateway routes to a supplier and bills the call. Which supplier renders the image is invisible to the caller. Images are returned synchronously — there is no polling.

With the official Ark SDK (volcenginesdkarkruntime), point base_url at https://api.modelgo.ai/api/v3 and use your ModelGo API key as api_key.

1. Create an image

POST https://api.modelgo.ai/api/v3/images/generations

Text to image (4.0)

curl https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "A fluffy orange cat sitting on a sunny windowsill, 16:9 landscape, film grain",
    "size": "2K",
    "watermark": false
  }'

Text to image (5.0 pro)

curl https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-pro",
    "prompt": "A fluffy orange cat sitting on a sunny windowsill, 16:9 landscape, film grain",
    "size": "2K",
    "watermark": false
  }'

Text to image (5.0 lite)

curl https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-lite",
    "prompt": "A fluffy orange cat sitting on a sunny windowsill, film grain",
    "size": "2K",
    "watermark": false
  }'

Image to image / multiple references

curl https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-pro",
    "prompt": "Place the cat from the first image into the neon street of the second image",
    "image": ["https://example-cdn.com/cat.jpg", "https://example-cdn.com/street.jpg"],
    "size": "1280x720",
    "response_format": "b64_json"
  }'

Sequential sets (4.0)

Sequential (multi-image) output is enabled with sequential_image_generation: "auto". The model decides how many images to render from the prompt; max_images caps it. See the official documentation for the allowed range.

curl https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "Four shiba-inu posters in different styles: cyberpunk, watercolor, minimal, vintage film",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4}
  }'

For example, requesting 4 images returns 4 entries in data[], usage.generated_images = 4, and the call is billed as 4 × unit price.

OpenAI-compatible entry point

doubao-seedream-4.0 is also served on the OpenAI-compatible entry point POST https://api.modelgo.ai/v1/images/generations. The body carries the official Ark fields verbatim and the response keeps the official shape; billing is identical to the native entry point (see "Billing"). Any OpenAI SDK or client works without the Ark SDK.

curl https://api.modelgo.ai/v1/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "Four shiba-inu posters in different styles: cyberpunk, watercolor, minimal, vintage film",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4}
  }'

• n must be omitted or 1: Ark's Images API has no n, and n ≥ 2 is refused at creation (HTTP 400). Use sequential_image_generation: "auto" to render several images at once.
• Sequential sets behave exactly as on the native entry point: sequential_image_generation plus sequential_image_generation_options.max_images; for example, requesting 4 returns 4 and bills as 4 × unit price.
• Image to image / multiple references uses the JSON image field (as in the official API). Do not use the multipart /v1/images/edits endpoint — it is not enabled for this model and answers 400 model_protocol_not_offered.
• Every other field (size, watermark, response_format, stream, …) carries the same limits as the native entry point; see "Parameters" and "Differences from the official API".

Response

{
  "model": "doubao-seedream-5.0-pro",
  "created": 1757318400,
  "data": [{"url": "https://ark-content-generation.tos-cn-beijing.volces.com/...", "size": "2816x1584", "output_format": "jpeg"}],
  "usage": {"generated_images": 1, "input_images": 0, "output_tokens": 17424, "total_tokens": 17424}
}

• model always echoes the logical model you requested (e.g. doubao-seedream-4.0), not Ark's internal version id (which looks like doubao-seedream-5-0-260128 / doubao-seedream-4-5-251128 / doubao-seedream-4-0-250828).
• response_format defaults to url; the link is valid for 24 hours — download promptly and do not persist the URL.
• With response_format: "b64_json", data[].b64_json carries the base64 image directly.
• data[].size is the actual output resolution. data[].output_format (encoding) and usage.input_images are returned by 5.0 pro / 5.0 flash only; 4.0 / 4.5 / 5.0 lite responses carry neither.
• usage.output_tokens / total_tokens are informational values echoed from upstream and are not billed; settlement uses usage.generated_images only.
• In a sequential set, a failed image appears as its own {"error": {...}} entry while the rest are returned; only successfully generated images are billed.
• On 5.0 lite with tools: [{"type":"web_search"}], the search count is echoed in usage.tool_usage.web_search and billed separately as an addon.

Save to a file:

curl -s https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedream-5.0-lite","prompt":"a red ball on a wooden table","size":"2K","response_format":"b64_json"}' \
  | python3 -c 'import sys,json,base64; open("out.jpg","wb").write(base64.b64decode(json.load(sys.stdin)["data"][0]["b64_json"]))'

2. Parameters

Field names, types, defaults and per-model support follow the official API reference. The table adds ModelGo's current behaviour where it differs.

• Any field outside the table → 400; unknown fields are rejected, not ignored (stricter than the official API, which does not guarantee an error).
• Routing follows deliverable tiers. The gateway prefers suppliers that can deliver the declared size; if none claims that tier it still routes to an available supplier and lets it decide (a 400 if unsupported).

Resolution tiers

size accepts a tier such as 1K / 2K / 4K or an explicit WxH such as 1280x720 or 2048x2048. The tier sets the total pixel budget; the exact dimensions come from the composition described in the prompt or from an explicit WxH. Available tiers and pixel bounds differ by model — the table above lists common values; see the official Ark documentation for the full constraints. An out-of-range value returns HTTP 400 and is never silently downgraded or upgraded. Nothing is charged.

Reference image requirements

• Must be a direct link the upstream server can GET: no auth, no redirects, no Referer / Cookie dependency.
• Some sites return 403 to non-browser fetches, which fails the request — not billed. Use your own object storage or CDN.

3. Full example (Python, official Ark SDK)

import os, requests
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ["MODELGO_API_KEY"], base_url="https://api.modelgo.ai/api/v3")

# 5.0 pro: tier + aspect described in the prompt
r = client.images.generate(model="doubao-seedream-5.0-pro",
                           prompt="An orange cat on a windowsill, 16:9 landscape, film grain",
                           size="2K", watermark=False)
img = r.data[0]
print(r.model, img.size, r.usage.generated_images)
open("cat.jpg", "wb").write(requests.get(img.url, timeout=60).content)

# 5.0 lite: default 2K tier (2048x2048)
l = client.images.generate(model="doubao-seedream-5.0-lite",
                           prompt="An orange cat on a windowsill, film grain",
                           size="2K", watermark=False)
open("cat-lite.jpg", "wb").write(requests.get(l.data[0].url, timeout=60).content)

# Multiple references
e = client.images.generate(model="doubao-seedream-5.0-pro",
                           prompt="Place the cat from the first image into the neon street of the second image",
                           image=["https://example-cdn.com/cat.jpg", "https://example-cdn.com/street.jpg"],
                           size="1280x720")
open("cat-neon.jpg", "wb").write(requests.get(e.data[0].url, timeout=60).content)

4. Billing

• Per image: settlement uses usage.generated_images at a flat price per image, independent of the size tier. A sequential set of N images is billed as N × the unit price.
• Both entry points price identically: the Ark native and OpenAI-compatible entries feed the same metering (image_generation_calls = images actually generated), so the same request is charged the same on either.
• One price per model: 4.0 / 5.0 pro / 5.0 lite / 5.0 / 4.5 each have their own price card in the console's model list and the prices differ (5.0 and 5.0 lite share one price).
• A reservation is frozen at request time (for the number of images the request can produce) and settled on the actual number generated; the difference is released.
• Rejected requests (400) and failed generations are never billed; the reservation is released automatically.
• An HTTP 200 whose data[] contains no url / b64_json at all (e.g. every entry is an error) is not billed.
• A content-moderation refusal (e.g. OutputImageSensitiveContentDetected) returns HTTP 400 with the upstream error code; it is neither billed nor retried.

5. Differences from the official API

The differences below are deliberate gateway behaviour; every other field, value range and default matches the official API reference (aligned with the official documentation).

Common errors