Seedream 5.0 Pro 画像 API の使い方

Seedream 5.0 Pro は、1 つの POST リクエスト、1 つの API キー、そして 1 つのフォローアップステップで動かせます。 ジョブを送信し、task_id を受け取り、画像が完成するまでステータスを確認します。その 2 つ目のステップを飛ばすと、最終ファイルは手に入りません。

手短に言うとこうです。

• https://api.apimart.ai/v1/images/generations にリクエストを送ります
• Authorization: Bearer YOUR_API_KEY を追加します
• model を doubao-seedream-5-0-pro に設定します
• prompt、size、n を含めます
• 新しい画像アイデアには テキストから画像 を使います
• 出力を 1 枚以上の参照画像に近づけたいときは 画像から画像 を使います
• 画像 URL は 24 時間で失効するので、すぐに保存します
• 3K 画像のような遅い出力には非同期ジョブを使います。約 35〜50 秒かかることがあります
• 料金は 画像 1 枚あたり約 $0.0320 なので、コストに注意します

私が最も覚えておきたいこと： キーはサーバー側に保ち、n は数値として渡し、長いジョブにはポーリングか webhook を使うことです。

いくつかの詳細は見た目以上に重要です。たとえば、401 はキーが欠けているか Bearer の形式が間違っていることを意味することが多いです。403 はキーは機能するが、アカウントがそのモデルを使えないか残高が少ないことを意味することが多いです。そして Base64 出力を使う場合、ブラウザで表示する前に data:image/...;base64, プレフィックスを自分で追加する必要があります。

クイック比較

要するに： このガイドは、認証のセットアップ方法、リクエストボディの構築方法、T2I と I2I の選択、非同期ジョブの処理、そしてファイルを失ったり支出を無駄にしたりせずに結果を保存する方法を示します。

2. API アクセスと認証をセットアップする

2.1 APIMart アカウントを作成し API キーを生成する

APIMart のウェブサイトにアクセスし、新しいアカウントにサインアップします ^[8]。次に、ダッシュボードで API キー管理ページ を開き、API キーを生成します ^[1][5]。

そのキーをすぐにコピーし、サーバー側に保管します。シークレットマネージャーか環境変数が最も安全な保管場所です。

API キーをフロントエンドのコードや公開リポジトリに置かないでください。誰かがそのキーを入手すると、あなたのアカウントを使えてしまいます。Node.js では process.env.API_KEY で保管します。シェル環境では export API_KEY="your-key-here" を使います ^[1][6]。

完全なリクエストフローを構築する前に、小さな POST リクエストを送ってアクセスが機能することを確認しましょう ^[1][2]。200 OK レスポンスが返れば、キーと権限は正しくセットアップされています。

その後、モデルとプロンプトを含むリクエストフィールドに進めます。

2.2 ベース URL と Bearer 認証ヘッダーを設定する

T2I か I2I のモードを選び、キーの準備ができたら、どんな画像リクエストも機能する前に認証をセットアップする必要があります。これらのヘッダーをすべてのリクエストで送ります。

Bearer プレフィックスが重要です。省くと、リクエストは失敗します ^[2][5]。また、Bearer の後にはちょうど半角スペース 1 つを使ってください。

HTTP ステータスコードは、認証の問題を素早く見つけるのに役立ちます ^[1][10]。401 Unauthorized エラーは通常、キーが欠けているか、無効か、Bearer プレフィックスが含まれていなかったことを意味します ^[1][10]。403 Forbidden エラーは通常、キー自体は有効だが、アカウントにモデルアクセスや十分な残高がないことを意味します ^[1][10]。

これを確かめる良い方法は、まず cURL でテストすることです。cURL が機能するのにアプリが機能しないなら、バグはおそらくアプリのリクエストコードにあります ^[2][6]。

認証を設定したら、次のステップは画像リクエストボディの構築です。

3. Seedream 5.0 Pro 画像リクエストを構築する

3.1 必須フィールド：モデル、プロンプト、サイズ、画像数

認証をセットアップしたら、次のステップは JSON ボディの構築です。

有効なリクエストボディには 4 つのフィールドが必要です。model、prompt、size、n です。

Seedream 5.0 Pro では、model を doubao-seedream-5-0-pro に設定します ^[1]。prompt フィールドは自然言語の説明を受け付け、最大 5,000 文字までサポートします ^[2]。size フィールドは出力の寸法またはアスペクト比を制御します。一般的な値には 1024x1024、2K、そして 1:1 や 16:9 のようなアスペクト比が含まれます ^[1][2]。n フィールドは生成する画像の枚数を設定し、通常 1〜15 です ^[1][6]。

小さな詳細が人をつまずかせることがあります。n は文字列ではなく整数でなければなりません。1 の代わりに "1" を渡すと、API は検証エラーを返します ^[1][5]。

3.2 任意フィールド：参照画像、Web 検索、非同期ジョブ

image_urls は画像から画像モードの主なフィールドです。これを使って、最大 14 枚の参照画像を URL または Base64 データ URI として送ります。各画像は 10 MB 未満で、1:3 から 3:1 の間のアスペクト比を使う必要があります ^[1]。Base64 を使う場合は、完全な Data URI プレフィックス data:image/jpeg;base64, を含めてください。そうでないとリクエストは失敗します ^[1][5]。

web_search は、最新のイベントやブランドロゴのような、事実に基づく、あるいはリアルタイムなプロンプトに役立ちます ^[4][7]。ほとんどの標準的な画像生成では、必要ありません。

非同期またはバッチジョブでは、callback_url が公開 HTTPS エンドポイントを受け付け、そこに APIMart がタスク完了ペイロードを POST します ^[2]。

3.3 cURL と JavaScript でのサンプル API 呼び出し

以下は、1 枚の 1024×1024 画像のための最小限で動作する cURL リクエストです。

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

そして、以下は fetch を使った Node.js での同じリクエストです。

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

このリクエストはサーバー側に保ちます。API キーをクライアント側のコードに絶対に露出させないでください。

リクエストを送信したら、次のステップはレスポンスペイロードの解析です。

4. レスポンスを処理し、一般的な画像ワークフローを実行する

4.1 画像 URL、Base64 出力、エラーオブジェクトを解析する

リクエストが完了すると、1 枚を送っても複数枚を送っても、レスポンスの形は同じままです。

成功したレスポンスは、4 つのトップレベルフィールドを持つ JSON オブジェクトを返します。model、created（Unix タイムスタンプ）、data（画像オブジェクトの配列）、usage です ^[6]。生成された各画像は、リクエストした形式に基づいて、url または b64_json 文字列のいずれかとして data 内に現れます。n が 1 より大きい場合、data には出力 1 枚ごとに 1 つの画像オブジェクトが含まれます。

URL 形式を使った場合、data の各項目は画像リンクを .url に格納します。その値をブラウザの画像 src に設定できます。1 つ注意点があります。これらは一時的な署名付きリンクで、24 時間後に失効します ^[6]。本番アプリでは、URL を保存する代わりに、すぐにファイルをダウンロードして永続的なストレージに保存してください。

Base64 形式を使った場合、data の各項目は生の文字列を .b64_json に格納します。これには data:image/...;base64, プレフィックスは_含まれません_ ^[6]。ブラウザで表示するには、そのプレフィックスを自分で追加します。

img.src = "data:image/png;base64", + data.b64_json;

Python でファイルとして保存するには、まずデコードします。

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

リクエストが失敗した場合、レスポンスには code と message フィールドが含まれます ^[6]。400 は通常、サポートされていないサイズか無効なパラメータを意味します。401 はリクエストが認証されていないことを意味します。毎回、両方のフィールドをログに記録してください。ほとんどの場合、message が問題を直接指し示します。

これらのフィールドを使って、出力を保存すべきか、デコードすべきか、表示すべきかを判断します。

---

4.2 Seedream 5.0 Pro で生成できる 3 つの一般的な画像タイプ

これら 3 つのパターンは、先に扱ったモード（テキストのみ、単一参照、複数参照）に対応します。

• テキストのみのマーケティングビジュアル。 より詳細さが必要なキャンペーンアセットには、3K 解像度（size: "3K"）を使い、被写体とシーンレイアウトから始めて、ライティング、スタイル、色の詳細を加える構造化された prompt を書きます。3K 生成は 35〜50 秒かかるので、通常は非同期のほうが良い選択肢です。

• 単一参照の製品バリエーション。 image_urls に 1 枚の参照画像を入れた画像から画像モードと、背景、ライティング、表面のテクスチャなど、変えたいものだけを変える焦点を絞った prompt を使います。これにより、ゼロから生成するよりも、製品の形とディテールをソース画像に近く保てます。3K のバリエーションには callback_url を使ってください。各タスクは約 40 秒かかることがあるからです ^[2]。

• ブランドとキャラクターの一貫性のための複数参照の一貫性。 キャラクターやブランド要素を複数の画像で一貫させる必要がある場合は、image_urls を通じて最大 14 枚の参照画像を渡します ^[2][3]。参照入力から複数の出力を作るときは sequential_image_generation を auto に設定すると、視覚的な一貫性を失わずにバリエーションを保てます ^[5][4]。これはソーシャルコンテンツシリーズ、製品カタログ、キャラクターシートにうまく機能します。

これらのパターンは、レスポンス形式がワークフローに合っているときに最もうまく機能する傾向があります。

---

4.3 同期リクエストと非同期リクエスト、URL レスポンスと Base64 レスポンス

統合を出荷する前に、この比較を使ってレスポンス形式を選んでください。

非同期ジョブでは、最初のポーリングまで約 20 秒待ち、その後 3 秒ごとに確認します ^[2]。本番では、ポーリングループを避けてサーバーのオーバーヘッドを削減できるため、callback_url のほうが良い選択肢です ^[2][9]。

デフォルトでは URL レスポンスを使います。同じレスポンス内に画像データが必要なときだけ Base64 に切り替えます。

5. 信頼できる Seedream 5.0 Pro 統合のための最終チェックリスト

最初のテスト呼び出しが成功したら、本番にスケールする前にこのチェックリストを一通り確認しましょう。ローンチを冷え込ませがちな問題を捕まえるシンプルな方法です。

認証とキーのセキュリティ。 API キーは環境変数かシークレットマネージャーに保ちます。リクエストはバックエンドから Authorization: Bearer <your_key> で送ります。

送る前にリクエストパラメータを検証する。 モデル文字列を確認し、n を整数として渡し、image_urls を許可された制限内に保ち、要求した size がサポートされていることを確認します。

素早いプレビューより長くかかるジョブでは、配信経路をそれに合わせて調整する。 出力サイズに基づいてタイムアウトを設定し、長時間実行のジョブにはポーリングの代わりに callback_url を使います。

画像の準備ができたら、配信を単なるレスポンスの問題ではなくストレージの問題として扱う。 URL 出力を使う場合は、すぐにファイルをダウンロードして永続的なストレージに移します。署名付き URL は 24 時間後に失効します ^[6]。

スケールアップする前に、小さなバッチでプロンプトをテストする。 Seedream 5.0 は生成画像 1 枚あたり約 $0.0320 で課金されます ^[2]。レイテンシと支出を監視できるように、createTime、completeTime、costTime をログに記録します ^[2]。

よくある質問

::: faq

task_id を受け取った後、非同期画像ジョブをどうやって確認しますか？

返された task_id を使って、非同期画像ジョブのステータスを確認します。

API が提供するステータスエンドポイントに GET リクエストを送ります。多くの API では、次のような形になります。

• /v1/tasks/{task_id}
• または task_id を使ったクエリスタイルのエンドポイント

本番利用では、タスク作成後、最初のステータス確認まで約 20 秒待ちます。その後、ジョブステータスが completed を示すまで、3 秒ごとにポーリングします。

ジョブが完了したら、レスポンスペイロードを読み、そこから 画像 URL を取り出します。 :::

::: faq

Base64 の代わりに URL 出力を使うべきなのはいつですか？

ほとんどの場合、URL 出力を使います。生成された画像への直接リンクが得られ、Web やモバイルアプリに組み込みやすくなります。

Base64 は、メモリベースの処理や、2 回目のリクエストを省きたい場合のように、レスポンスボディ内にインラインで画像データが必要なときだけ使います。高解像度の 4K アセットには、通常 URL 出力のほうが効率的です。 :::

::: faq

生成した画像を失わない最良の方法は何ですか？

生成した画像は速やかに保存してください。API の画像リンクは 72 時間しか有効でないからです。

Seedream 5.0 Pro API は非同期で動作します。つまり、画像 URL はすぐには得られません。まずタスク ID を受け取ります。次に、そのタスク ID を使って画像 URL を取得します。

出力を失わないために、主な選択肢は 2 つあります。

• 画像の準備ができるまでタスク ID でポーリングする
• コールバック URL を使って、リンクが失効する前にシステムが画像を受信、キャプチャ、保存できるようにする

待ちすぎると、URL は失効し、画像が失われる可能性があります。 :::