Seedream 5.5 APIチュートリアル：生成、編集、移行

Seedream 5.5への移行で重要なのは、モデル名を置き換えることだけではなく、ファイルのワークフローです。画像を生成し、返されたタスクを確認して画像を保存し、その保存したバイト列を編集時の参照画像として送信します。

AIHubMixのSeedream 5.5では現在、doubao-seedream-5-5とPOST /ai/v1/images/generationsを使用します。このチュートリアルでは、陶器のマグカップの商品画像を生成し、色だけを変更する編集をリクエストします。

対象範囲：2026年11月12日時点でドキュメントを確認済みです。コードについては、ローカルでの構文チェックとオフラインのヘルパーチェックのみ実施しており、生成リクエストは実行していません。これらは、出力品質、編集の忠実度、レイテンシ、実際の請求額を裏付けるものではありません。

1. 明確で簡潔なリクエストを準備する

Python 3.10以降とrequestsを使用します。Bashで依存関係をインストールし、シェルの履歴に値を残さないようにAPIキーを入力します。

python3 -m pip install requests
read -r -s -p 'AIHubMix API key: ' AIHUBMIX_API_KEY
printf '\n'
export AIHUBMIX_API_KEY

デプロイするコードでは、シークレットマネージャーを通じて環境変数を設定してください。キーをソースファイル、リクエスト例、ログ、ノートブック、ブラウザー側のコードに含めないでください。どちらかのPOSTを実行する前に、非同期タスクガイドの説明に従って、アカウントのタスク機能を有効にしてください。この前提条件は、同期的な待機を含む/ai/v1ネイティブのメディアタスクエンドポイントに適用されます。バックグラウンド実行を選ぶかどうかとは別の要件です。

最新のモデルエンドポイントスキーマを確認し、配列の位置ではなくpathで該当項目を選択してください。モデル固有の制約は、共通パラメーター一覧より優先されます。

スキーマではmodelと空でないpromptが必須で、nは1に制限され、出力形式としてpngとjpegが指定されています。imageにはURL、Base64入力、または{url}オブジェクトを指定でき、imagesには公開上限が参照画像14枚の配列を指定できます。この上限はここでは実行時にテストしていません。この例では参照画像を1枚使用し、デフォルトのサイズを明示的に指定します。外側のinputオブジェクトやextra拡張は使いません。

2. 画像を生成し、タスクを確認してPNGを保存する

統合画像APIのドキュメントでは、id、object: image、model、status、output、errorを含むタスクレスポンスが定義されています。従来形式のdata[0].urlとして読み取らないでください。

まず短いワークフローを確認してください。完全なセットアップとダウンロード用ヘルパーは、以下の折りたたまれた付録にあります。これらの例を実行する前に、付録のコードブロックを同じPythonセッションに一度読み込んでください。このコードでは、画像リクエストを送信せずにsettings、api_json、collectを定義します。その後、短いコードブロックを順番に実行してください。POSTはそれぞれ別の有料アクションです。レスポンスがない場合やダウンロードに失敗した場合でも、修復のために再実行しないでください。

画像リクエストを一度だけ送信する

generation = {
    **settings,
    "prompt": "Product photograph of one matte blue ceramic mug on a cream tabletop, "
              "soft side lighting, plain warm-gray background, no text or logos.",
}
task = api_json("POST", IMAGES + "/generations", generation)

タスクを確認してからPNGを保存する

asyncを省略すると、同期的に完了を待ちます。HTTP 200でもstatus: failedが含まれる場合があります。ヘルパーはステータス確認の前にタスク IDを保存し、completedの場合のみダウンロードに進みます。failed、cancelled、不明なステータスの場合は処理を停止します。pendingとin_progressの場合は、既存タスクを確認してください。生成を再度リクエストしてはいけません。

collect(task, "mug-blue")

この呼び出しは、作成時に使用したキーで完了済みの出力を取得し、PNGのバイト列を検証してmug-blue.pngとして保存します。作成リクエストの自動再試行は行わず、キーを転送する前に想定外のダウンロードホストやリダイレクトを拒否します。完全な実装は付録にあります。これはドキュメントに基づく動作であり、生成結果を検証したものではありません。

モデルガイドによると、出力URLの有効期間は約30分です。同じBearerヘッダーを使って速やかにダウンロードし、バイト列を自分で保存してください。expires_at: nullは、無期限に保持されることを意味しません。b64_jsonに値が設定されている場合は、URLからダウンロードせずにデコードしてください。

3. 保護されたダウンロードURLではなく、ローカルファイルを編集する

編集に費用をかける前に、保存した画像を自分で確認してください。認証済みクライアントでダウンロードできるcontent_urlが、画像プロバイダーも取得できる公開URLとは限りません。ローカルのPNGをData URIとして再アップロードします。

reference = Path("mug-blue.png").read_bytes()
if not reference.startswith(b"\x89PNG\r\n\x1a\n"):
    raise SystemExit("The editing reference must be the saved PNG.")
edit = {
    **settings,
    "prompt": "Change only the mug color from blue to forest green. Preserve the mug shape, "
              "camera angle, tabletop, background, lighting, and shadows.",
    "image": "data:image/png;base64," + base64.b64encode(reference).decode("ascii"),
}
task = api_json("POST", IMAGES + "/generations", edit)
collect(task, "mug-green")

このリクエストは画像の保持を求めるものであり、保持されたことを実証するものではありません。有料の次の処理に進む前に、結果を確認してください。インラインエンコードを含むJSONリクエスト全体は32 MiB以内である必要があり、モデル固有のメディア制限も適用されます。実際に公開され、プロバイダーからアクセスできる画像URLも、入力方法として利用できます。

4. 任意：非同期処理の待機と中断からの復旧

セクション1のアカウント要件と実行モードは別のものです。403 async_not_enabledは、コンソールでタスク機能を有効にする必要があることを示します。任意なのはバックグラウンド実行のみです。

バックグラウンドで生成する場合は、同じgeneration辞書を作成し、以下の2行を、同期処理のtask = api_json(...)行と、別途実行するcollect(...)呼び出しの両方の代わりに使用してください。送信前に実行モードを決めてください。両方のバージョンを実行してはいけません。

task = api_json("POST", IMAGES + "/generations", {**generation, "async": True})
collect(task, "mug-blue", poll=True)

ヘルパーは、終端状態になるまで約15秒ごとにGET /ai/v1/images/{id}を呼び出します。これはドキュメントに記載された推奨ポーリング間隔であり、サーバーが強制する間隔ではありません。Webhookを使うにはasync: trueが必要です。受信側の実装はこのチュートリアルの対象外です。

結果の取得処理が停止した場合、必要に応じて新しいセッションに付録の共通セットアップ／ヘルパー部分だけを読み込んでください。作成用のコードブロックは読み込まないでください。IDが保存されている場合は、POSTせずに再開できます。

task_id = Path("mug-blue.task-id").read_text(encoding="utf-8").strip()
task = api_json("GET", IMAGES + "/" + quote(task_id, safe=""))
collect(task, "mug-blue", poll=True)

編集の復旧には、対応するmug-greenのファイル名の先頭部分を使ってください。作成レスポンスが失われ、IDも保存されていない場合は、代わりに最近のタスクを確認します。

recent = api_json("GET", IMAGES + "?limit=20&order=desc")
for row in recent.get("data", []):
    print(row.get("id"), row.get("model"), row.get("status"), row.get("created_at"))

モデルと作成時刻が一致するものを選び、最新のタスクを無条件に選ばないでください。必要に応じて、次のリクエストのafterカーソルにnext_afterを使用してください。一致するタスクを特定できない場合は、再送信するのではなくサポートに問い合わせてください。一覧はスナップショットです。ポーリングにはタスク詳細を使用してください。行のoutput_errorは、出力を読み取れなかったことを意味します。生成結果がなかったことや、料金が変わったことを示すものではありません。

作成時に使用したキーを引き続き使用してください。特に、統合タスクの一覧、詳細、コンテンツへのアクセスはトークンごとに分離されています。同じアカウントでも、別のキーではそれらのタスクを読み取れません。ローカルで処理が中断されても、失敗したことや料金が発生していないことの証明にはなりません。

5. 移行時の間違いと現在のエラー

旧式のDoubaoアダプターのドキュメントでは、古いIDを/v1/models/doubao/<id>/predictionsの下で、inputエンベロープとともに使用しています。掲載されているモデル一覧に5.5はありません。ここでは、検出可能な5.5のルートとフラットなリクエストボディを使用してください。旧形式での生成失敗はテストしていません。ドット区切りの表記がエイリアスだと決めつけず、現在のハイフン区切りのIDをそのまま使用してください。

最上位のquality、background、aspect_ratio、seedは、このモデルの現在のスキーマにはないため引き継がないでください。ByteDanceのローンチ発表ではネイティブの透過RGBA出力について説明されていますが、ゲートウェイのスキーマにはbackgroundもlayer_decompositionもありません。PNGを選ぶだけで透過画像を生成できることは確認されていません。

以下は統合画像APIでドキュメント化されているエラーであり、Seedream 5.5で実際に観測されたものではありません。HTTPステータスとタスクステータスを別々に確認し、メッセージ全体の文字列ではなくcodeに基づいて分岐してください。

HTTP 502 task_status_unavailableについて、ガイドには次のように記載されています。

モデルプロバイダーのタスク状態を確認できませんでした。再送信しないでください。タスク IDまたはリクエスト IDを添えてサポートに問い合わせてください。

タスクレベルのresult_delivery_failedについては、次のように記載されています。

生成結果を配信できませんでした。自動的に再送信しないでください。タスク IDを添えてサポートに問い合わせてください。

sync_timeoutが発生しても、処理が実行されなかったとは限りません。error.tidを保存し、実際に返された場合に限りタスク IDを使用して、不確かな結果の解決をサポートに依頼してください。復旧可能なダウンロードエラーの場合は、生成ではなく取得を再試行してください。410 artifact_expiredは別のエラーで、その成果物はもう取得できません。まず保存済みファイルを確認してください。置き換えが引き続き必要な場合は、新たな有料生成を意図的に承認してください。429 too_many_downloadsの場合は、保存済みのコピーを確認するか、サポートに問い合わせてください。待つだけでアクセスが再開するとは限りません。

ガイドでは、失敗したタスク内で報告された場合も含め、output_blockedに対する生成料金を明示的に免除しています。この例外を、すべての失敗リクエストやモデレーション対象のリクエストに適用しないでください。output_policy_violationには既存のモデレーション時の課金ルールが適用されます。

6. 1回の出力だけでなく、ワークフロー全体の費用を見積もる

Sina Technologyのローンチ報道では、画像の入力と出力を合わせて、2Kの正方形画像を1回編集する費用は約CNY 0.28で、テキストトークンは無料とされています。これは報道に基づく情報であり、公式料金表での確認やAIHubMixからの見積もりではありません。

例として、既存画像に対して有料の編集を2回行い、どちらもこの概算シナリオに当てはまる場合、費用は約2 × CNY 0.28 = CNY 0.56です。初回のテキストから画像への生成、追加の参照画像、追加候補、再試行は含まれません。実測された請求額ではありません。

この生成後に編集する例では、合計 = 初回の生成料金 + 参照画像の編集料金として見積もってください。確認したページからは5.5の公式料金全体を確定できなかったため、このチュートリアルでは固定の合計額も、旧モデルと新モデルの正確な節約率も示していません。

送信前に確認すること：

• 現在のID、ルート、フラットなリクエストボディ、モデルスキーマを確認する。
• キーは環境変数に保管し、復旧に備えてタスク IDを保存する。
• POSTはそれぞれ別の有料アクションとして扱い、ダウンロードの再試行に使わない。
• 編集前にタスクのステータスと保存済み画像を確認します。
• 正しいMIMEタイプを指定して、ローカルのバイトデータを再アップロードします。
• 別の生成を試す前に、結果が不確かなタスクを復旧します。

まず画像1枚に対して意図的な編集を1回行い、ファイルを確認してから追加の編集を行います。

付録：共通セットアップとダウンロード用ヘルパー

ワークフローを読むだけの場合は、この付録をスキップしてください。短いコード例を実行する前に、このブロックを展開し、同じ Python セッションに一度だけ読み込んでください。セッションを設定して関数を定義しますが、画像は生成しません。新しいセッションで中断したタスクを復旧する場合は、生成用や編集用のブロックではなく、このブロックだけを再度読み込んでください。

import base64
import os
import time
from pathlib import Path
from urllib.parse import quote, urlsplit

import requests

BASE = "https://aihubmix.com"
IMAGES = "/ai/v1/images"
settings = {
    "model": "doubao-seedream-5-5",
    "size": "2048x2048",
    "n": 1,
    "output_format": "png",
    "response_format": "url",
}
client = requests.Session()
client.headers["Authorization"] = "Bearer " + os.environ["AIHUBMIX_API_KEY"]


def api_json(method, path, body=None):
    try:
        response = client.request(
            method, BASE + path, json=body,
            timeout=(15, 600), allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(
            "Connection interrupted. Recover the existing task before another POST."
        ) from None
    try:
        data = response.json()
    except ValueError:
        raise SystemExit(
            f"HTTP {response.status_code}: non-JSON response; recover before another POST."
        ) from None
    if not isinstance(data, dict):
        raise SystemExit("Unexpected response; recover before another POST.")
    if not 200 <= response.status_code < 300:
        error = data.get("error") or {}
        raise SystemExit(
            f"HTTP {response.status_code}: code={error.get('code')}, "
            f"tid={error.get('tid')}. No automatic generation retry."
        )
    return data


def collect(task, stem, poll=False):
    task_id = task.get("id")
    if not isinstance(task_id, str) or not task_id:
        raise SystemExit("No task ID returned. Recover from the task list; do not resubmit.")
    Path(stem + ".task-id").write_text(task_id + "\n", encoding="utf-8")
    while True:
        status = task.get("status")
        print("Task:", task_id, "status:", status)
        if status == "completed":
            break
        if status not in {"pending", "in_progress"}:
            error = task.get("error") or {}
            raise SystemExit(
                f"Stopped: status={status}, code={error.get('code')}; task={task_id}."
            )
        if not poll:
            raise SystemExit("Task still active. Query the saved ID; do not recreate it.")
        time.sleep(15)
        task = api_json("GET", IMAGES + "/" + quote(task_id, safe=""))

    output = task.get("output") or []
    if not output:
        raise SystemExit("Completed without readable output; investigate the saved task.")
    item = output[0]
    if item.get("b64_json"):
        image_bytes = base64.b64decode(item["b64_json"], validate=True)
    else:
        url = item.get("content_url")
        if not isinstance(url, str):
            raise SystemExit("Missing content_url; investigate the saved task.")
        parsed = urlsplit(url)
        if (parsed.scheme, parsed.netloc) != ("https", "aihubmix.com"):
            raise SystemExit("Unexpected download origin; key was not forwarded.")
        try:
            response = client.get(url, timeout=(15, 120), allow_redirects=False)
        except requests.RequestException:
            raise SystemExit("Download interrupted; recover this task, not a new generation.") from None
        if not 200 <= response.status_code < 300:
            try:
                detail = response.json()
            except ValueError:
                detail = {}
            error = detail.get("error", {}) if isinstance(detail, dict) else {}
            code = error.get("code") if isinstance(error, dict) else None
            if response.status_code == 410 or code == "artifact_expired":
                raise SystemExit("Artifact expired; retrieval cannot recover it. Check saved files first.")
            if code == "too_many_downloads":
                raise SystemExit("Download allowance exhausted; check saved files or contact support.")
            raise SystemExit(
                f"Download HTTP {response.status_code}, code={code}; "
                "inspect the saved task. Retry retrieval only if recoverable."
            )
        image_bytes = response.content
    if not image_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
        raise SystemExit("Expected PNG bytes; stopped before saving or reusing the result.")
    destination = Path(stem + ".png")
    destination.write_bytes(image_bytes)
    print("Saved:", destination)
    return destination

600秒の読み取りタイムアウトはクライアント側の設定であり、サービスのレイテンシを保証するものではありません。PNGの確認は、このチュートリアルで出力形式を明示的に指定していることに対応しています。JPEGを選ぶ場合は、それに合わせて変更してください。

よくある質問

Seedream 5.5で使うモデル IDとエンドポイントはどれですか？
doubao-seedream-5-5を使用し、フラットなJSON形式でPOST /ai/v1/images/generationsを呼び出します。別の表記や旧式のアダプターも同等だと決めつけないでください。

このチュートリアルには、テスト済みの生成結果が含まれていますか？
いいえ。コードはドキュメントに基づいており、ローカルでの構文確認とオフラインでのヘルパー確認のみを行っています。推論リクエスト、画像品質の測定、レイテンシの測定、課金テストは実行していません。

非同期処理は必須ですか？
いいえ。デフォルトでは同期的に待機します。バックグラウンド実行にはブール値のasync: trueを使います。同期的に待機する場合でも、ネイティブのメディアタスクエンドポイントを使うには、アカウントレベルでタスク機能が有効になっている必要があります。

HTTP 200なら画像生成は成功したということですか？
いいえ。タスクのステータスとエラーを確認してください。HTTPリクエストが成功していても、タスクは失敗している場合があります。ダウンロードするのは、タスクの完了後にしてください。

生成結果のダウンロードURLを、次の編集で参照画像として使えますか？
使えると決めつけないでください。生成時に使ったキーでダウンロードし、ローカル画像をデータURIとしてエンコードするか、実際に公開されている画像URLを指定してください。

タイムアウトや応答の消失が発生したら、どうすればよいですか？
生成を自動的に再実行しないでください。保存済みのタスク IDを確認するか、生成時に使ったキーで画像一覧からタスクを復旧してください。リクエスト IDを保管し、結果が不確かな場合はサポートに問い合わせてください。

PNGを選べば、透明な画像やCNY 0.28の請求が保証されますか？
どちらも保証されません。スキーマには、確認済みの透明度制御はありません。CNY 0.28は報道で紹介された2K編集の概算例であり、AIHubMixの見積もりでも、テキストから画像を生成して編集する場合の固定価格でもありません。

続けて読む：Seedream 5.5シリーズ

• 既存の5.0 Proのワークフローを変更する前に、アップグレードの価値を検討しましょう。Seedream 5.5と5.0 Proの比較：アップグレードする価値はある？
• 同じワークフローで別の画像モデルも使える場合は、それぞれのトレードオフを比較しましょう。Seedream 5.5とGPT Image 2.6 Sunburstの比較：どちらを選ぶべき？

出典

1. Seedream 5.5のローンチ発表 — ByteDance Seed。ベンダーによる機能の説明。
2. Seedream 5.5の最新エンドポイントスキーマ — AIHubMix。リクエストフィールドとモデル固有の制約。
3. 統合画像生成API — AIHubMix。タスク、ダウンロード、最新のエラー情報。
4. Seedream 5.5モデルガイド — AIHubMix。モデル IDと有効期間の短い認証付きダウンロード。ルート固有のエラーについては、統合APIのドキュメントを参照してください。
5. Seedream 5.5のローンチ報道 — Sina Technology。編集コストの概算例であり、公式料金ではありません。