Seedream
Seedream で画像を生成・編集する:パラメータ、レスポンス、注意事項。
| 項目 | 値 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 生成(参照画像による編集を含む) | POST /v1/images/generations |
| 編集(multipart 互換の入口) | POST /v1/images/edits |
| キーのグループ | 「Seedream 画像生成グループ」 |
Seedream は結果を同期で返します(Lite と 4.5 はストリーミングも可)。n は 1 固定で、組画像とレイヤー分解を除き 1 回に 1 枚を生成します。画像リンクは 24 時間有効です。
利用できるモデル
| モデル | モデル ID | サイズ略称 | 公式価格 |
|---|---|---|---|
| Seedream 5.5 | seedream-5-5 | 1K / 1.5K / 2K | $0.02〜/ 枚 |
| Seedream 5.0 Pro | seedream-5-0-pro | 1K / 1.5K / 2K | $0.0225〜/ 枚 |
| Seedream 5.0 Lite | seedream-5-0-lite | 2K / 3K / 4K | $0.035/ 枚 |
| Seedream 4.5 | seedream-4-5 | 2K / 4K | $0.04/ 枚 |
選び方:1K を出力できるのは 5.5 と 5.0 Pro だけで、どちらも1.5K は 1K と同価格で生成品質が上のため 1.5K を優先してください。Lite と 4.5 の最小出力は 2K です。
リクエストパラメータ
生成
POST /v1/images/generations に JSON ボディで送ります。image を加えると、1 枚の編集、複数画像の合成、部分編集になります。
| パラメータ | 必須 | 型と制限 | デフォルト | 説明 |
|---|---|---|---|---|
model | 必須 | 文字列、上表を参照 | — | キーで GET /v1/models が返す ID を使う |
prompt | 必須 | 文字列、前後の空白を除いて空でない | — | 内容、構図、スタイル、編集指示。layer_decomposition 時は省略可 |
size | 任意 | モデルのサイズ略称、または WIDTHxHEIGHT | — | auto は layer_decomposition 時のみ、画素範囲は下表 |
n | 任意 | 1 のみ | 1 | それ以外(null を含む)は 400。複数枚は sequential_image_generation を使う |
response_format | 任意 | url / b64_json のみ | url | url は署名付きリンク、b64_json は data[].b64_json に base64 を返す |
output_format | 任意 | モデル別、下表を参照 | — | 出力画像の形式 |
optimize_prompt_options | 任意 | オブジェクト、mode はモデル別 | — | プロンプト最適化モード |
image | 任意 | URL / Data URL、文字列または文字列配列 | — | 参照画像。渡すと画像編集になる |
layer_decomposition | 任意 | ブール値、seedream-5-0-pro のみ | false | true で入力画像 1 枚をベース画像 + レイヤーに分解。レイヤー分解を参照 |
background | 任意 | opaque / transparent、seedream-5-5 / seedream-5-0-pro のみ | opaque | transparent は透過チャンネル付きの入力画像がちょうど 1 枚必要。透過背景を参照 |
watermark | 任意 | ブール値 | false | true で透かしを入れる(公式のデフォルトは true) |
sequential_image_generation | 任意 | auto / disabled、seedream-5-0-lite / seedream-4-5 のみ | disabled | auto で複数枚の組画像を返す。組画像を参照 |
sequential_image_generation_options | 任意 | オブジェクト。max_images は 1〜15 の整数 | — | 組画像の上限枚数。参照画像数 + max_images ≤ 15 |
stream | 任意 | ブール値、seedream-5-0-lite / seedream-4-5 のみ | false | true で SSE を返す。ストリーミングを参照 |
モデル別の制限:
| モデル ID | size の総ピクセル数 | 参照画像の上限 | output_format | optimize_prompt_options.mode |
|---|---|---|---|---|
seedream-5-5 | 921,600〜4,624,220 | 10 | png / jpeg | standard |
seedream-5-0-pro | 921,600〜4,624,220 | 10 | png / jpeg | standard / fast |
seedream-5-0-lite | 3,686,400〜16,777,216 | 14 | png / jpeg | standard |
seedream-4-5 | 3,686,400〜16,777,216 | 14 | jpeg | standard |
WIDTHxHEIGHT のアスペクト比は 1:16〜16:1 の範囲内にしてください。size が不正な場合は生成前に 400 が返り、課金されません。
image の各要素は http(s) URL または base64 の Data URL で、Data URL は 1 枚 30 MB 以下です。対応形式は JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF です。URL は送信時にダウンロードもサイズ確認もされないため、サーバーから取得できる公開アドレスにしてください。
部分編集にマスクは使いません。参照画像に直接注釈を描き込み、その座標 / bbox / 矢印 / 塗りつぶした領域をプロンプトで説明してください。
編集
POST /v1/images/edits は、既存の OpenAI Images 編集コード向けの互換入口です。multipart/form-data を推奨し、生成と同じ JSON も受け付けます。参照画像は 1 枚以上必要です。
| パラメータ | 必須 | 型と制限 | デフォルト | 説明 |
|---|---|---|---|---|
image / image[] | 必須 | ファイルまたは URL 文字列、繰り返し可 | — | アップロードは 1 枚 30 MB 以下 |
model、prompt | 必須 | 「生成」と同じ | — | — |
size、n、response_format、output_format | 任意 | 「生成」と同じ | — | — |
background、watermark、stream、sequential_image_generation | 任意 | 「生成」と同じ | — | multipart ではブール値を文字列 true / false で書く |
sequential_image_generation_options[max_images] | 任意 | 「生成」の max_images と同じ | — | max_images でも可 |
optimize_prompt_options[mode] | 任意 | 「生成」の mode と同じ | — | optimize_prompt_mode でも可 |
layer_decomposition | 任意 | 「生成」と同じ。multipart では文字列 true | false | image はちょうど 1 枚 |
mask フィールドがあると 400 になります(null でも同じ)。上表にない multipart フィールドは無視されます。
レスポンス
標準の OpenAI Images JSON で同期的に返り、画像は data[].url(response_format: b64_json のときは data[].b64_json)に入ります。stream: true のときは SSE になります。ストリーミングを参照してください。
| フィールド | 型 | 説明 |
|---|---|---|
created | integer | Unix 秒 |
model | string | リクエストしたモデル ID |
data[].url | string | 署名付き画像リンク、24 時間有効 |
data[].b64_json | string | base64 画像データ。response_format: b64_json のときのみ |
data[].error | object | 組画像のみ:この 1 枚の生成に失敗(code、message)、課金なし |
data[].size | string | 実際の出力 WIDTHxHEIGHT |
usage | object | 返ることがあり、generated_images などを含む |
usage.cost | number | このリクエストの課金額の人民元額(usage.cost_usd と同じ課金額)。小数点以下最大 6 桁。課金された同期の成功レスポンスには必ず含まれる |
usage.cost_usd | number | このリクエストで残高から実際に差し引かれた米ドル額。小数点以下最大 8 桁で、使用状況のこのレコードと同じ金額 |
usage.currency | string | usage.cost の通貨。常に CNY |
{
"model": "seedream-5-0-pro",
"created": 1760000000,
"data": [
{
"url": "https://…/result.jpeg?X-Signature=…",
"size": "2048x2048"
}
],
"usage": {
"generated_images": 1,
"output_tokens": 16384,
"total_tokens": 16384,
"cost": 1.53,
"cost_usd": 0.225,
"currency": "CNY"
}
}同期の成功レスポンスには、このリクエストの実際の課金額も含まれます。本文の usage.cost・usage.cost_usd・usage.currency、および同じ値のレスポンスヘッダー X-HopBase-Cost・X-HopBase-Cost-USD・X-HopBase-Currency です。生成に時間がかかり(約 40 秒以上)、接続維持のためにサーバーが先に 200 のヘッダーを送っている場合、ヘッダーには課金額が入りません。本文の usage.cost_usd(米ドル、使用記録と一致)または usage.cost(人民元)で照合してください。課金されなかった失敗にはいずれも付かず、ストリーミングのレスポンスにも付きません(使用記録を確認してください)。詳しくは課金を参照してください。
返される URL は24 時間有効な署名付きリンクです。期限が切れると再取得できず、再生成(再度課金)するしかないため、受け取ったらすぐにダウンロードしてください。
例
テキストから画像
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "ネオンに照らされた夜の未来都市、映画的な構図",
"size": "2048x2048",
"response_format": "url"
}'参照画像で編集
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "1 枚目のカップを右側へ移動し、他はそのまま",
"image": ["https://example.com/source.png"],
"size": "2K",
"output_format": "png",
"response_format": "url"
}'組画像
seedream-5-0-lite と seedream-4-5 は、関連する複数枚の画像を 1 回のリクエストで返せます(n は 1 のまま)。"sequential_image_generation": "auto" を指定すると、モデルが prompt から枚数を決めます。上限は sequential_image_generation_options.max_images(1〜15 の整数。参照画像数 + max_images は 15 以下)です。「同じキャラクターの四季を描いた 4 枚のイラスト」のように、組全体を prompt で説明してください。/v1/images/edits の multipart では sequential_image_generation_options[max_images](または max_images)を送ります。
- 課金は成功した枚数のみです。失敗した 1 枚(多くはコンテンツ審査)は
data[].error(code、message)として返り、課金されません。全枚失敗した場合は理由付きで 400 になります。 - ストリーミングでない組画像は全枚の完了後に返り、サーバーは最大約 280 秒待ちます。枚数が多い場合は
stream: trueで 1 枚ずつ受け取ってください。ストリーミングでない組画像ではresponse_format: b64_jsonは使えません。
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-lite",
"prompt": "Four illustrations of the same shiba inu in spring, summer, autumn and winter",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"size": "2K"
}'ストリーミング
seedream-5-0-lite と seedream-4-5 は "stream": true に対応し、単一画像でも組画像でも使えます。レスポンスは SSE(text/event-stream)です。seedream-5-5 と seedream-5-0-pro は 400 になります。
| イベント | data |
|---|---|
image_generation.partial_succeeded | 1 枚完成:image_index、url(または b64_json)、size |
image_generation.partial_failed | 1 枚失敗:image_index、error.code、error.message。課金なし |
image_generation.completed | 全体の完了:usage.generated_images、usage.output_tokens、usage.total_tokens |
各イベントの data には type、model、created も入り、ストリームは data: [DONE] で終わります。成功した枚数で課金されます。ストリーミングのレスポンスには usage.cost や X-HopBase-Cost などのヘッダーが付かないため、課金額はコンソールの使用記録で確認してください。
curl -N https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-lite",
"prompt": "Four illustrations of the same shiba inu in spring, summer, autumn and winter",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"stream": true
}'event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"seedream-5-0-lite","created":1792723998,"image_index":0,"url":"https://…","size":"2048x2048"}
event: image_generation.completed
data: {"type":"image_generation.completed","model":"seedream-5-0-lite","created":1792723998,"usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}
data: [DONE]透過背景
seedream-5-5 と seedream-5-0-pro は background に opaque / transparent を指定でき、デフォルトは opaque です。transparent は画像編集のみで使え、PNG など透過チャンネル付きの入力画像をちょうど 1 枚渡します(JPEG・BMP の Data URL は 400)。出力は透過付き PNG のため、output_format: jpeg は 400 になります。ほかのモデルで background を渡すと 400 です。
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-your-key" \
-F "model=seedream-5-0-pro" \
-F "prompt=Keep the product and make the background transparent" \
-F "image=@product.png" \
-F "background=transparent" \
-F "output_format=png"レイヤー分解
seedream-5-0-pro は 1 枚の画像を、ベース画像と最大 16 枚の透明レイヤー(被写体、文字、背景、装飾)に分解できます。レイヤーごとに編集・移動してから合成し直せます。POST /v1/images/generations に JSON のブール値 "layer_decomposition": true を渡すか、POST /v1/images/edits にフィールド layer_decomposition=true を渡します(multipart でも JSON でも可)。
有効にすると、次のルールが変わります。
| パラメータ | layer_decomposition: true のとき |
|---|---|
model | seedream-5-0-pro のみ。ほかのモデルは 400 |
image | ちょうど 1 枚。Data URL は PNG か JPEG |
prompt | 任意。省略するとモデルが被写体・文字・背景・装飾を自動で識別します。分解したい内容を書くか、<bbox>x1 y1 x2 y2</bbox>(0–999 の正規化座標)で領域を指定することもできます |
size | 1K / 1.5K / 2K / auto のみ、デフォルト auto。WIDTHxHEIGHT は不可 |
output_format | ベース画像にのみ適用。レイヤーは常に透過付き PNG |
auto の場合、入力画像が約 1280x720〜2048x2048 の範囲なら元のサイズのまま、それより小さければ 1K、大きければ 2K で出力されます。入力画像の公式制限:総画素数 512x512〜6000x6000、アスペクト比 1:16〜16:1、30 MB 以下。
レイヤー分解は同期で、時間がかかります(1K で約 1.5 分)。クライアントのタイムアウトは5 分以上に設定し、最初のリクエストが処理中のうちは再送しないでください。最初のリクエストが完了して課金されることがあります。
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-pro",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"size": "1K"
}'data[] には先頭にベース画像、続いて各レイヤーが入ります。
{
"model": "seedream-5-0-pro",
"created": 1792722728,
"data": [
{
"url": "https://…/base.jpeg?X-Signature=…",
"size": "880x1088",
"output_format": "jpeg",
"z_index": 0
},
{
"url": "https://…/layer-1.png?X-Signature=…",
"size": "959x354",
"output_format": "png",
"z_index": 1,
"bounding_box": {
"absolute": [156, 751, 784, 983],
"normalized": [177, 690, 890, 903]
},
"name": "Wooden stump stage",
"description": "A wooden stump stage at the bottom of the scene"
}
],
"usage": {
"generated_images": 2
}
}| フィールド | 説明 |
|---|---|
data[].z_index | 0 がベース画像。レイヤーは 1 から増え、大きいほど上に重なる |
data[].url | 署名付きリンク、24 時間有効 |
data[].size | その画像の実際のピクセルサイズ。レイヤー画像のサイズは、ベース画像上の枠と通常一致しない |
data[].output_format | ベース画像はリクエストの output_format、レイヤーは png |
data[].bounding_box.absolute | レイヤーのみ:ベース画像上の [left, top, right, bottom] ピクセル座標 |
data[].bounding_box.normalized | レイヤーのみ:同じ枠の 0–999 正規化座標 |
data[].name、data[].description | レイヤーのみ:レイヤー名と内容の説明 |
usage.generated_images | ベース画像 + レイヤーの枚数(課金枚数) |
合成するときは、ベース画像をキャンバスにして z_index の昇順に重ねます。各レイヤーを枠のサイズ (right - left) x (bottom - top) に拡大縮小し、アルファチャンネルを使って (left, top) に貼り付けます。Pillow の例:
import io
import urllib.request
from PIL import Image
def fetch(url):
return Image.open(io.BytesIO(urllib.request.urlopen(url).read())).convert("RGBA")
items = sorted(resp["data"], key=lambda d: d["z_index"]) # resp はパース済みのレスポンス JSON
canvas = fetch(items[0]["url"])
for item in items[1:]:
left, top, right, bottom = item["bounding_box"]["absolute"]
layer = fetch(item["url"]).resize((right - left, bottom - top))
canvas.alpha_composite(layer, (left, top))
canvas.save("recomposed.png")注意事項
nは 1 のみ:1 回に 1 枚を生成します。例外は組画像(sequential_image_generation: auto、Lite と 4.5)とレイヤー分解(5.0 Pro)です。- 同期のみ:
Prefer: respond-asyncは無視され、同期で返ります。 - デフォルトは
urlです。base64 が必要ならresponse_format: b64_jsonを指定します(ストリーミングでない組画像ではstream: trueも必要)。 sizeはautoを受け付けず(レイヤー分解を除く)、Lite と 4.5 の最小出力は 2K です。seedream-4-5の出力は JPEG のみです。seedream-5-5のoptimize_prompt_options.modeはstandardのみで(fastは 400)、レイヤー分解・組画像・ストリーミングには対応しません。- 従来のマスクには対応しないため、部分編集は注釈付きの参照画像とプロンプトで指示してください。
- 複数形の
images、qualityなどは効果がなく、無視されます。 tools(Web 検索)にはまだ対応しておらず、渡すと 400 になります。seedream-5-0-liteは Seedream 5.0 の軽量版で公開モデル名は Seedream 5.0 Lite のため、Pro として使わないでください。- Data URL は base64 エンコードが必須で、MIME は画像と一致させてください。
- 公式仕様:入力画像は 1 枚あたり最大 30 MB / 36MP です。
よくあるエラー
パラメータが不正な場合は生成前に 400 が返り、課金されません。コンテンツの安全チェックで拒否された場合も 400 で課金されず、理由は error.message に入ります。
| エラー | 対処 |
|---|---|
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | そのモデルのサイズ略称か正しい WIDTHxHEIGHT を使う |
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | 1K・1.5K・2K か正しい WIDTHxHEIGHT を使う。4K は指定不可 |
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216 | 総ピクセル数が範囲内になるよう幅と高さを調整 |
size aspect ratio must be between 1:16 and 16:1 | アスペクト比を調整 |
only a single output is supported (n=1) | n を外す。複数枚は sequential_image_generation を使う |
response_format only supports url or b64_json | url か b64_json にする |
model seedream-4-5 only supports output_format jpeg | jpeg を渡すか省略する |
model seedream-5-5 only supports optimize_prompt_options.mode standard | standard を渡すか省略する。fast は seedream-5-0-pro を使う |
at most 10 reference images are supported | 参照画像を減らす |
seedream does not accept a traditional mask; ... | mask を外し、注釈付きの参照画像を使う |
model seedream-5-0-lite does not support layer_decomposition | レイヤー分解は seedream-5-0-pro を使う |
layer_decomposition requires exactly one image | image を 1 枚だけ渡す |
layer_decomposition only accepts png or jpeg images | 入力画像を PNG か JPEG に変換する |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition | サイズ段階を使うか、size を省略する |
layer_decomposition must be a boolean | true か false を渡す |
model seedream-5-0-lite does not support background | background は seedream-5-5 か seedream-5-0-pro を使う |
background transparent requires exactly one image with an alpha channel | PNG など透過付きの画像を 1 枚だけ渡す |
background transparent outputs png; output_format jpeg is not allowed | output_format を外すか png にする |
model seedream-5-0-pro does not support sequential_image_generation | 組画像は seedream-5-0-lite か seedream-4-5 を使う |
the number of reference images plus max_images must not exceed 15 | max_images を減らすか参照画像を減らす |
response_format b64_json with sequential_image_generation auto requires stream=true | stream: true を付けるか url にする |
model seedream-5-0-pro does not support stream | ストリーミングは seedream-5-0-lite か seedream-4-5 を使う |
model seedream-5-0-lite does not support tools | tools を外す |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # 例: "size": "auto"
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # 例: "size": "4K"
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216
size aspect ratio must be between 1:16 and 16:1
missing prompt
response_format only supports url or b64_json
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
model seedream-5-0-lite only supports optimize_prompt_options.mode standard
model seedream-5-5 only supports optimize_prompt_options.mode standard # fast は seedream-5-0-pro のみ
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference # /v1/images/edits に画像がない
seedream does not accept a traditional mask; ... # /v1/images/edits に "mask" があると拒否、null でも同じ
model seedream-5-0-lite does not support layer_decomposition # 対応は seedream-5-0-pro のみ
layer_decomposition must be a boolean
layer_decomposition requires exactly one image # 画像なし、または 2 枚以上
layer_decomposition only accepts png or jpeg images # Data URL がほかの形式
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition
model seedream-5-0-lite does not support background # 対応は seedream-5-5 / seedream-5-0-pro のみ
model seedream-5-0-pro only supports background opaque or transparent
background transparent requires exactly one image with an alpha channel
background transparent outputs png; output_format jpeg is not allowed
background transparent requires an input image with an alpha channel, image/jpeg is not supported
model seedream-5-0-pro does not support sequential_image_generation # 組画像とストリーミング:seedream-5-0-lite / seedream-4-5 のみ
sequential_image_generation only supports auto or disabled
sequential_image_generation_options must be an object
sequential_image_generation_options.max_images must be an integer between 1 and 15
the number of reference images plus max_images must not exceed 15
response_format b64_json with sequential_image_generation auto requires stream=true
model seedream-5-0-pro does not support stream
watermark must be a boolean
model seedream-5-0-lite does not support tools # Web 検索は未対応課金
生成に成功した枚数で課金され(組画像で失敗した分は課金なし)、5.5 と 5.0 Pro は参照画像 1 枚ごとにも課金されます。生成失敗と安全チェックによる拒否は課金されません。5.5 と 5.0 Pro は出力ピクセル数の段階で価格が決まり、1K と 1.5K は同価格です。各リクエストの実際の課金額はレスポンスの usage.cost_usd(米ドル)と usage.cost(人民元)で確認できます。レイヤー分解では、出力画像(ベース画像と各レイヤー)の 1 枚ごとに、それぞれのピクセル段階でレイヤー分解の単価が課金されます。単価は 5.0 Pro の通常の 1 枚あたり価格の半額です。入力画像は通常どおり参照画像として課金されます。usage.generated_images が課金された出力枚数です。ストリーミングのレスポンスには課金額のフィールドがないため、使用記録で確認してください。
単価は各モデルカードとログイン後のモデルカタログを参照してください。