指南 / 模型

Seedream 5.0 Pro API

Seedream 5.0 Pro 的全部输入字段、字段之间的规则、价格，以及完整的请求和响应示例。

POST/v1/generations"model": "seedream-5-0-pro"

Generates one image from a prompt and optional reference images.

What it does

Seedream 5.0 Pro makes one high-resolution image from a prompt, at 2K, 3K or a custom size up to 4K. Add up to 10 reference images to edit a picture, keep a product or character, or borrow a style. The prompt goes in input.prompt and the reference images in input.image; whether you send image chooses the mode:

Mode	Fields that select it	Other fields to set
[Text to image](#text-to-image)	`prompt` only	`size` (optional)
[Reference images and editing](#reference-images-and-editing)	`prompt`, `image` with 1 to 10 items	`size` (optional)

Every task returns exactly one image. For a set of related images in one task, use Seedream 5.0 Lite.

Every example below is a complete body for POST /v1/generations. Send the same body to POST /v1/estimates first: it is free, creates no task, holds no Credits, and refuses an invalid body with the same 422 as a create. The https://media.vizoapi.com/... files are public samples, so the examples run as they are; replace them with your own files or uploaded ast_... asset IDs.

Modes

Text to image

Send only prompt. Pick the size with size: 2k, 3k, or an exact WIDTHxHEIGHT (see [Output](#output)). For 4K, send the pixel size, such as 3840x2160; the word 4k is refused.

Text to image

{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A paper boat on a still pond at dawn, mist on the water, soft natural light, photorealistic, shallow depth of field",
    "size": "2k"
  }
}

4K landscape

{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Wide cinematic view of a black monolith on an empty savanna at sunrise, long shadows, fine film grain",
    "size": "3840x2160",
    "output_format": "jpeg",
    "seed": 42
  }
}

Reference images and editing

Put 1 to 10 images in image, in the order you want to name them. With one image, the prompt can edit it: change an object, the background, the light or the style, and say what must stay. With several, combine them: a character from one, a place from another, the style of a third. Name each by its order in the prompt ("image 1", "image 2").

An 11th image is refused (rule too_many_items). Each item is a public https URL or an ast_... asset ID; anything else is refused (rule bad_format). The first reference image is included in the price; each one after it adds a small charge (see [How it is billed](#how-it-is-billed)).

Edit one image

{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Replace the black monolith in image 1 with a tall crystal obelisk; keep the landscape, light and composition unchanged",
    "image": [
      "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg"
    ],
    "size": "2k"
  }
}

Combine references

{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Poster: the ring-shaped space station from image 2 hangs in the sky above the monolith and savanna from image 1, golden hour, clean title space at the top",
    "image": [
      "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg",
      "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg"
    ],
    "size": "2304x3072"
  }
}

Prompt optimization

Any mode can set "optimize_prompt": true to have the prompt rewritten before generation. optimize_prompt_options tunes it: thinking is auto, enabled or disabled, and mode is only standard. Sending optimize_prompt_options without "optimize_prompt": true is refused (rule optimize_options_without_optimize). The price does not change.

Optimized prompt

{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "cozy reading corner, rainy evening",
    "optimize_prompt": true,
    "optimize_prompt_options": { "thinking": "enabled", "mode": "standard" },
    "size": "3k"
  }
}

Input limits

Limit	Value	Checked
`prompt`	Required and not blank	At create, 422 `invalid_input` (`required`, `bad_format`)
`image` items	Up to 10	At create, 422 `invalid_input` (`too_many_items`)
Image value	Public `https` URL (up to 4,000 characters) or `ast_...` asset ID	At create, 422 `invalid_input` (`bad_format`)
`size`	`2k`, `3k`, or `WIDTHxHEIGHT` with 3,686,400 to 10,404,496 pixels in total	At create, 422 `invalid_input` (`bad_format` for the shape, `size_invalid` for the pixel count)
Image file	PNG, JPEG, WebP, BMP, TIFF, GIF, HEIC; up to 30 MB	At create when readable: 422 `input_media_invalid` (format) or `input_media_too_large` (size)
Uploaded asset	`image/png`, `image/jpeg`, `image/webp`; up to 20,000,000 bytes	When you request the upload, 422
Reference pixel size and aspect ratio; output aspect ratio	Checked by the model only	When the task runs: the task fails with `generation_failed` and is not charged

Plain http, private or local addresses, URLs with a user name or #fragment, and Base64 data are refused with 422 (rule bad_format). The model fetches a linked image itself, possibly some time after acceptance, so keep it reachable until the task closes; if it cannot, the task fails with generation_failed. See Model inputs and media.

Output

Setting	Values
`size`	`2k`, `3k`, or `WIDTHxHEIGHT` with 3,686,400 to 10,404,496 pixels, for example `2048x2048` (1:1), `2560x1440` (16:9), `2304x3072` (3:4), `3840x2160` (4K 16:9) or `3200x3200`. When omitted, the model picks its default size
`output_format`	`jpeg` only (the default); `png` is refused with 422 because this model always returns JPEG
`seed`	`-1` (or omitted) for random, or a non-negative integer to repeat a result more closely
`optimize_prompt`	`false` (default) or `true` to rewrite the prompt first
`watermark`	`false` (default) or `true` for a visible watermark

A succeeded task lists one JPEG image in result.outputs: take its asset_id and get a download URL with download an asset. Outputs are kept for 7 days. See Get results.

How it is billed

The model has one tier, standard, priced per output image. The listed price, 20 Credits per image, already covers every size this model accepts, from 2K to 4K, so size, output_format, seed, optimize_prompt and watermark do not change it.

Reference images: the first is included; each one after it adds the extra input image charge shown in the [Pricing](#pricing) section below.

Request	Output images	Reference images	Held
Text to image, any size	1	0	20.000
Edit one image	1	1	20.000
Combine 3 references	1	3	20.000 + 2 × the extra input image charge (see [Pricing](#pricing))

A succeeded task is charged for the image delivered, plus the same reference image charge, so price.charged equals the hold. A failed, canceled or unresolved task is not charged and its hold is released. Send the body to POST /v1/estimates to see the exact hold and its basis (outputs, input_images, large). See Billing.

Errors and behaviors

When	Response	What to do
A field the schema does not list, a wrong value or type	422 `invalid_input`, `errors[].rule` such as `field_not_allowed`, `value_not_allowed`, `wrong_type`, `out_of_range`	Send only the fields in the reference below; `model` belongs outside `input`
A missing or blank `prompt`	422 `invalid_input`, rule `required` or `bad_format`	Send a prompt
More than 10 reference images	422 `invalid_input`, rule `too_many_items`	Send at most 10
A `size` outside the pixel range, or a name other than `2k` and `3k`	422 `invalid_input`, rule `size_invalid` or `bad_format`	Use `2k`, `3k` or a valid `WIDTHxHEIGHT`
`optimize_prompt_options` without `"optimize_prompt": true`	422 `invalid_input`, rule `optimize_options_without_optimize`	Set `optimize_prompt` or drop the options
A linked image has the wrong format or is too large	422 `input_media_invalid` or `input_media_too_large`	Convert or shrink it
The model refuses or cannot fetch an image	Task fails with `generation_failed`	Check the file and keep the URL public until the task closes, or upload it; nothing is charged
Content safety refuses the prompt or a reference image	Task fails with `input_moderated`	Change the prompt or image; nothing is charged
Content safety refuses the result	Task fails with `output_moderated`, no result	Change the prompt; nothing is charged
The model fails for another reason	Task fails with `generation_failed`	Retry, or change the prompt; nothing is charged

Moderation is always on; no field turns it off. Each task has a 24-hour deadline from acceptance. A task still unfinished then closes as unresolved, releases its hold and is not charged; if its result arrives later, it is added at no charge and late_result_available becomes true. See Errors and Get results.

Prompting tips

Describe the picture, not the process: subject, setting, composition, light, lens and style. "Close-up product shot on white marble, soft window light, 85 mm" works better than a list of keywords.
Pick size for the framing you want. A tall 2304x3072 suits posters and phone screens, a wide 3840x2160 suits banners and desktop backgrounds.
To edit, say exactly what changes and what stays: "replace the sky with a storm; keep the people, their pose and the framing unchanged".
With several references, name each by its order and say what to take from it: "the jacket from image 2 on the person in image 1, in the style of image 3".
Put text you want in the image in quotes, and say where it goes: a title "NORTH STAR" at the top, in bold white letters.
Keep seed fixed while you adjust the wording, to see what the wording changes.

价格

每张输出图片按档位价格计费。

档位	选择条件	价格
`standard`	任意输入	每张 20 积分

规则

optimize_prompt_options is allowed only with optimize_prompt set to true.

输入字段

在 input 中发送这些字段。表中没有的字段会被拒绝，返回 HTTP 422 invalid_input。

输入字段
字段	说明
`prompt`string必填	Text prompt. Must not be blank.
`seed`integer可选	Random seed; -1 picks one at random. 最小 -1 · 最大 9223372036854775807
`size`string可选	Output size: WIDTHxHEIGHT with 3,686,400 to 10,404,496 pixels in total, or 2k or 3k. 格式`^([1-9][0-9]x[1-9][0-9]\|2k\|3k)$`
`image`array of strings可选	Reference images, up to 10. 最多 10 项
`optimize_prompt`boolean可选	Rewrites the prompt before generation. 默认值 `false`
`optimize_prompt_options`object可选	Allowed only with optimize_prompt set to true.
`optimize_prompt_options.thinking`string可选	Prompt expansion. 可选值`autoenableddisabled`
`optimize_prompt_options.mode`string可选	Optimization mode. Only standard. 固定值 `standard`
`output_format`string可选	Image file format. Seedream 5.0 Pro returns JPEG only. 可选值`jpeg` 默认值 `jpeg`
`watermark`boolean可选	Add a visible watermark. Defaults to false; the tier price is unchanged. 默认值 `false`

示例

完整的创建请求、202 响应，以及任务成功后的状态。

请求

cURL

curl https://api.vizoapi.com/v1/generations \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A paper boat on a pond at dawn, soft watercolor"
  },
  "metadata": {
    "client_reference": "my-unique-reference-1"
  }
}'

Python

import os, requests

# Send once: do not retry this request automatically.
task = requests.post(
    "https://api.vizoapi.com/v1/generations",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    json={
      "model": "seedream-5-0-pro",
      "input": {
        "prompt": "A paper boat on a pond at dawn, soft watercolor"
      },
      "metadata": {
        "client_reference": "my-unique-reference-1"
      }
    },
    timeout=60,
).json()
print(task["id"], task["status"])

Node.js

// Send once: do not retry this request automatically.
const res = await fetch("https://api.vizoapi.com/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "A paper boat on a pond at dawn, soft watercolor"
    },
    "metadata": {
      "client_reference": "my-unique-reference-1"
    }
  }),
});
const task = await res.json();
console.log(task.id, task.status);

此输入选择 standard 档位，每张 20 积分。一张图片冻结 20.000 积分。

响应

202 已受理

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "seedream-5-0-pro",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "processing",
  "execution_status": "processing",
  "delivery_status": "pending",
  "billing_status": "pending",
  "version": 1,
  "price": {
    "unit": "credit",
    "estimated": "20.000",
    "reserved": "0.000",
    "charged": "0.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": null,
  "error": null,
  "result": null
}

200 已成功

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "seedream-5-0-pro",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "succeeded",
  "execution_status": "succeeded",
  "delivery_status": "ready",
  "billing_status": "settled",
  "version": 4,
  "price": {
    "unit": "credit",
    "estimated": "20.000",
    "reserved": "0.000",
    "charged": "20.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": "2026-11-08T09:01:31Z",
  "error": null,
  "result": {
    "asset_id": "ast_01JD8Z9M2C4V",
    "outputs": [
      {
        "index": 0,
        "asset_id": "ast_01JD8Z9M2C4V",
        "content_type": "image/jpeg"
      }
    ]
  }
}