本文へスキップ

Seedream

Seedream で画像を生成・編集する:パラメータ、レスポンス、注意事項。

項目値
Base URLhttps://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.5seedream-5-51K / 1.5K / 2K$0.02〜/ 枚
Seedream 5.0 Proseedream-5-0-pro1K / 1.5K / 2K$0.0225〜/ 枚
Seedream 5.0 Liteseedream-5-0-lite2K / 3K / 4K$0.035/ 枚
Seedream 4.5seedream-4-52K / 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 のみurlurl は署名付きリンク、b64_json は data[].b64_json に base64 を返す
output_format任意モデル別、下表を参照—出力画像の形式
optimize_prompt_options任意オブジェクト、mode はモデル別—プロンプト最適化モード
image任意URL / Data URL、文字列または文字列配列—参照画像。渡すと画像編集になる
layer_decomposition任意ブール値、seedream-5-0-pro のみfalsetrue で入力画像 1 枚をベース画像 + レイヤーに分解。レイヤー分解を参照
background任意opaque / transparent、seedream-5-5 / seedream-5-0-pro のみopaquetransparent は透過チャンネル付きの入力画像がちょうど 1 枚必要。透過背景を参照
watermark任意ブール値falsetrue で透かしを入れる(公式のデフォルトは true)
sequential_image_generation任意auto / disabled、seedream-5-0-lite / seedream-4-5 のみdisabledauto で複数枚の組画像を返す。組画像を参照
sequential_image_generation_options任意オブジェクト。max_images は 1〜15 の整数—組画像の上限枚数。参照画像数 + max_images ≤ 15
stream任意ブール値、seedream-5-0-lite / seedream-4-5 のみfalsetrue で SSE を返す。ストリーミングを参照

モデル別の制限:

モデル IDsize の総ピクセル数参照画像の上限output_formatoptimize_prompt_options.mode
seedream-5-5921,600〜4,624,22010png / jpegstandard
seedream-5-0-pro921,600〜4,624,22010png / jpegstandard / fast
seedream-5-0-lite3,686,400〜16,777,21614png / jpegstandard
seedream-4-53,686,400〜16,777,21614jpegstandard

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 では文字列 truefalseimage はちょうど 1 枚

mask フィールドがあると 400 になります(null でも同じ)。上表にない multipart フィールドは無視されます。

レスポンス

標準の OpenAI Images JSON で同期的に返り、画像は data[].url(response_format: b64_json のときは data[].b64_json)に入ります。stream: true のときは SSE になります。ストリーミングを参照してください。

フィールド型説明
createdintegerUnix 秒
modelstringリクエストしたモデル ID
data[].urlstring署名付き画像リンク、24 時間有効
data[].b64_jsonstringbase64 画像データ。response_format: b64_json のときのみ
data[].errorobject組画像のみ:この 1 枚の生成に失敗(code、message)、課金なし
data[].sizestring実際の出力 WIDTHxHEIGHT
usageobject返ることがあり、generated_images などを含む
usage.costnumberこのリクエストの課金額の人民元額(usage.cost_usd と同じ課金額)。小数点以下最大 6 桁。課金された同期の成功レスポンスには必ず含まれる
usage.cost_usdnumberこのリクエストで残高から実際に差し引かれた米ドル額。小数点以下最大 8 桁で、使用状況のこのレコードと同じ金額
usage.currencystringusage.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_succeeded1 枚完成:image_index、url(または b64_json)、size
image_generation.partial_failed1 枚失敗: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 のとき
modelseedream-5-0-pro のみ。ほかのモデルは 400
imageちょうど 1 枚。Data URL は PNG か JPEG
prompt任意。省略するとモデルが被写体・文字・背景・装飾を自動で識別します。分解したい内容を書くか、<bbox>x1 y1 x2 y2</bbox>(0–999 の正規化座標)で領域を指定することもできます
size1K / 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_index0 がベース画像。レイヤーは 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)、レイヤー分解・組画像・ストリーミングには対応しません。
  • 従来のマスクには対応しないため、部分編集は注釈付きの参照画像とプロンプトで指示してください。

よくあるエラー

パラメータが不正な場合は生成前に 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 size1K・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_jsonurl か b64_json にする
model seedream-4-5 only supports output_format jpegjpeg を渡すか省略する
model seedream-5-5 only supports optimize_prompt_options.mode standardstandard を渡すか省略する。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 imageimage を 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 booleantrue か false を渡す
model seedream-5-0-lite does not support backgroundbackground は seedream-5-5 か seedream-5-0-pro を使う
background transparent requires exactly one image with an alpha channelPNG など透過付きの画像を 1 枚だけ渡す
background transparent outputs png; output_format jpeg is not allowedoutput_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 15max_images を減らすか参照画像を減らす
response_format b64_json with sequential_image_generation auto requires stream=truestream: 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 toolstools を外す

課金

生成に成功した枚数で課金され(組画像で失敗した分は課金なし)、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 が課金された出力枚数です。ストリーミングのレスポンスには課金額のフィールドがないため、使用記録で確認してください。

単価は各モデルカードとログイン後のモデルカタログを参照してください。

次のステップ