seedream-image

Seedream Image

POST https://api.acedata.cloud/seedream/images を使用します。Authorization: Bearer $ACEDATACLOUD_API_TOKEN で認証し、JSON リクエストボディを送信します。

初回セットアップ

1. clawhub install @acedatacloud/seedream で公式 Skill をインストールします。ClawHub の公開元が @acedatacloud であることを確認してください。
2. AceDataCloud → Applications にサインインし、General application を開いて、Seedream へのアクセス、残高、現在の料金を確認します。API キーをコピーするか、別のキーを作成するには Manage Keys → Create を選択します。Bearer を付けずにキーの値をコピーしてください。platform-... 形式の管理トークンはサービスの API キーではありません。
3. Allowed APIs の制限を有効にする場合は、/seedream/images と /seedream/tasks を含めてください。以下の高度なワークフローでは、追加のルートを呼び出す場合があります。
4. OpenClaw Gateway のホストで、~/.openclaw/.env に ACEDATACLOUD_API_TOKEN=your_api_key_here を設定し、Gateway を再起動して新しいセッションを開始します。ターミナルから直接テストする場合は、そのシェルで export ACEDATACLOUD_API_TOKEN="your_api_key_here" を実行します。キーをプロンプトに記載したり、.env ファイルをコミットしたりしないでください。
5. 以下の 生成または編集 の例に従います。このワークフローがタスク ID を返す場合は、完了するまで同じタスクを照会してください。進行状況を確認するためだけに、同じ課金対象リクエストを再送信しないでください。

キーの設定、初回実行、トラブルシューティングの図解 · トークンの詳細

要求する機能に応じてモデルを選択する

機能	Seedream 5.0 Pro	Seedream 5.0 Lite
モデル ID	doubao-seedream-5-0-pro-260628	doubao-seedream-5-0-lite-260128
画像を1枚生成／編集	はい	はい
参照画像	最大10枚	最大14枚
関連画像セット	いいえ	はい。入力＋出力 ≤ 15
ストリーミング／ウェブ検索	いいえ	はい
レイヤー分解／透明な背景	はい	いいえ
プロンプトの最適化	standard、fast	standard
プリセットサイズ	1K、1.5K、2K	2K、3K、4K

Seedream 4.5 と 4.0 も互換性のために引き続き利用できます。モデルがサポートしていないパラメーターは送信しないでください。

生成または編集

curl https://api.acedata.cloud/seedream/images \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-lite-260128",
    "prompt": "a four-panel storyboard of a courier crossing a rainy neon city",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4},
    "watermark": false
  }'

編集するには、image に URL／Base64 文字列を1つ、または配列を追加します。response_format は url または b64_json です。5.0 Pro／Lite では、output_format に jpeg または png も指定できます。明示的な寸法には WIDTHxHEIGHT を使用し、選択したモデルのピクセル数とアスペクト比の制限を満たす必要があります。

最新情報が重要な場合に限り、Lite のウェブ検索を使用します。

{"tools": [{"type": "web_search"}]}

透明な背景の Pro 編集

透明な PNG 入力を1つ使用し、PNG で出力します。

{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "replace the parrot with a peacock",
  "image": "https://example.com/layer.png",
  "background": "transparent",
  "output_format": "png",
  "size": "1.5K"
}

background とレイヤー分解を併用しないでください。transparent と JPEG の組み合わせは無効です。

画像を編集可能なレイヤーに分解する

layer_decomposition は Pro 専用で、PNG／JPEG がちょうど1つ必要です。自動分解する場合は prompt を省略し、希望する要素を自然な言葉で記述するか、正規化された <bbox> 座標を使用します。

curl https://api.acedata.cloud/seedream/images \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "image": "https://example.com/poster.png",
    "layer_decomposition": true,
    "size": "auto",
    "watermark": false
  }'

レスポンスには、ベース画像（z_index: 0）が1つと、最大16枚の透明な PNG レイヤーが含まれます。各レイヤーには name、description、bounding_box.absolute／normalized を含めることができます。再構成するには、各レイヤーをバウンディングボックスの幅と高さに合わせて拡大縮小し、left／top の位置に配置して、z_index の昇順で描画します。いずれかのレイヤーの処理に失敗すると、分解全体が失敗します。

非同期タスク

生成には時間がかかる場合があります。"async": true を推奨します。レスポンスには task_id が返されます。次の方法でポーリングします。

POST /seedream/tasks
{"action": "retrieve", "id": "<task_id>"}

非同期タスクのポーリングに従ってください。callback_url は、実際に公開されている Webhook がある場合に限り使用してください。ヘルスエンドポイントを偽のコールバックとして使用しないでください。

ストリーミング

Lite/4.x はストリーミングに対応しています。Accept: application/x-ndjson を指定して "stream": true を送信し、image_generation.completed まで、1 行につき 1 件の正規化された JSON イベントを読み取ってください。ストリーミングを async または callback_url と併用しないでください。

• image_generation.partial_succeeded：生成された画像 1 枚
• image_generation.partial_failed：失敗した項目 1 件。他の Lite 画像は引き続き成功する場合があります
• image_generation.completed：最終的な使用量と、課金が確定する唯一のイベント

エージェントツール

• MCP：pip install mcp-seedream-pro を実行し、seedream_generate_image、seedream_edit_image、seedream_decompose_image を使用した後、seedream_get_task でポーリングします。
• CLI：pip install seedream-cli を実行し、seedream generate、seedream edit、seedream decompose、または seedream generate --stream --json を使用します。
• ホスト型 MCP：https://seedream.mcp.acedata.cloud/mcp。

MCP 画像ツールは非同期のため、リアルタイムのストリーミングには REST または CLI を使用してください。

結果と課金に関する注意事項

• URL の有効期限は限られているため、ファイルは速やかに保存してください。
• Lite の data[] には、成功した画像と項目ごとの error オブジェクトが混在する場合があります。成功した画像のみを数えてください。
• Pro のレイヤー項目は実際の出力サイズに基づいて個別に課金されます。ベースと成功した各レイヤーは、それぞれ別にカウントされます。
• z_index、バウンディングボックス、項目エラー、tools、usage を保持してください。レスポンスを URL のリストに平坦化しないでください。
• 要求したサイズだけを基に、最終的な課金額を決して推定しないでください。返された cost／使用量と、最新の料金ページ（https://platform.acedata.cloud/services/seedream?tab=pricing）を参照してください。