APIMart
APIMart

Seedream 5.0 Pro で画像を生成する方法

APIMart で Seedream 5.0 Pro を呼び出すステップバイステップガイド:認証、リクエストフィールド、タスクのポーリング、結果の読み取り、リンク期限前の画像保存。

チュートリアル

Seedream 5.0 Pro は、POST リクエスト 1 回、API キー 1 つ、そしてもう 1 ステップで動かせます。タスクを送信して task_id を受け取り、画像が完成するまでタスクを確認します。Seedream 5.0 Pro は非同期モデルなので、最初のレスポンスに画像は含まれません。

要点だけまとめると:

  • リクエスト先は https://api.apimart.ai/v1/images/generations
  • ヘッダーに Authorization: Bearer YOUR_API_KEY を追加
  • model は seedream-5-0-pro
  • prompt に加えて、resolution(1K、1.5K、2K)と size(auto または 16:9 などの比率)を指定
  • 編集や合成をするときは image_urls に最大 10 枚の参照画像を入れる
  • GET /v1/tasks/{task_id} を 5〜10 秒ごとにポーリングし、ステータスが completed になるまで待つ
  • 画像リンクの有効期限は 72 時間 なので、結果はすぐにダウンロードする

いちばん大事なポイント:これは単一画像モデルです。1 回のリクエストで返る画像は 1 枚で、n が 1 より大きいと拒否されます。APIMart で Seedream 5.0 Pro API を試せます。全フィールドは API リファレンス を参照してください。

APIMart
Seedream 5.0 Pro API:リクエストとポーリングの早見表

重要なポイント

  • Seedream 5.0 Pro は、https://api.apimart.ai/v1/images/generations への POST リクエストで呼び出します。ヘッダーは Authorization: Bearer YOUR_API_KEY、model は seedream-5-0-pro です。
  • 出力ティアは resolution(1K、1.5K、2K)、形状は size(auto、10 種類の比率、または正確なピクセル数)で指定します。1.5K は 1K と同じ料金で、3K と 4K は 400 を返します。
  • 1 回のリクエストで生成される画像は 1 枚です。n が 1 より大きいリクエスト、グループ生成、ストリーミング、Web 検索はいずれも 400 で拒否され、タスクは作成されません。
  • 画像編集では image_urls で最大 10 枚の参照画像を、公開 URL または Base64 データ URI で送ります。
  • 最初のレスポンスに含まれるのは task_id だけです。タスクのエンドポイントを 5〜10 秒ごとにポーリングし、72 時間以内に画像を保存します。

クイック比較

項目使い道主な制限・注意点
テキストから画像生成プロンプトだけで新しい画像を作る入力画像は不要
単一参照の編集1 枚の画像の背景・照明・細部を変えるimage_urls に 1 枚
複数参照の編集人物・服装・シーンを合成する参照画像は最大 10 枚
レイヤー分解ポスターを編集可能なレイヤーに分ける入力画像はちょうど 1 枚、PNG レイヤーは最大 16 枚
透過背景アルファを保ったままレイヤーを編集するアルファ付きの入力画像 1 枚、output_format: "png"

まとめると:このガイドでは、認証の設定、リクエストボディの作成、タスクのポーリング、そしてファイルを失わずに結果を保存する方法を説明します。

1. API アクセスと認証を設定する

1.1 APIMart アカウントを作成して API キーを発行する

APIMart

APIMart に登録し、ダッシュボードの API キー管理ページ でキーを作成します。作成したらすぐにコピーし、サーバー側のシークレットマネージャーまたは環境変数に保存してください。

キーをフロントエンドのコードや公開リポジトリに置いてはいけません。キーを手に入れた人は誰でもあなたの残高を使えてしまいます。Node.js では process.env.APIMART_API_KEY から読み込み、シェルでは export APIMART_API_KEY="your-key-here" を使います。

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

すべてのリクエストはベース URL https://api.apimart.ai に送り、次の 2 つのヘッダーを付けます:

ヘッダー値
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json

Bearer の後のスペースはちょうど 1 つにします。トークンがない、または形式が正しくない場合は 401 が返ります。cURL では動くのにアプリでは動かない場合、原因はたいていアプリ側のヘッダーの組み立て方にあります。

2. Seedream 5.0 Pro の画像リクエストを作る

APIMart

2.1 主要フィールド:Model、Prompt、Resolution、Size

テキストから画像を生成するリクエストには model と prompt が必要です。さらに 2 つのフィールドで出力を制御します:

  • model:seedream-5-0-pro(seedream-5.0-pro も可)。
  • prompt:自然言語による説明。中国語と英語に加えて、日本語、韓国語、スペイン語、ポルトガル語、フランス語、ドイツ語、ロシア語、インドネシア語、ベトナム語などのテキストもネイティブに描画できます。目安は英語で約 600 語以内です。長すぎると細部が失われることがあります。
  • resolution:1K(デフォルト)、1.5K、2K。1.5K は 1K と同じ料金なので、通常は 1.5K がおすすめです。
  • size:auto(デフォルト)、10 種類の比率(1:1、4:3、3:4、16:9、9:16、3:2、2:3、2:1、1:2、21:9)のいずれか、または 2048x1024 のような正確なピクセル数。正確なピクセル数は合計 921,600〜4,624,220、縦横比は 1:16〜16:1 の範囲にする必要があります。

たとえば resolution: "1.5K" と size: "16:9" を組み合わせると、2048×1152 の画像が返ります。

2.2 オプションのフィールド

オプションのパラメーター型使う場面
image_urlsArray画像編集と複数参照の合成。公開 URL または Base64 データ URI を最大 10 個
output_formatStringjpeg(デフォルト)または png
backgroundStringもともとアルファチャンネルを持つ画像 1 枚を編集するとき、transparent で透過を保持(png が必要)
layer_decompositionBoolean1 枚の画像をベース画像と最大 16 枚の透過 PNG レイヤーに分解
optimize_prompt_optionsObjectプロンプト最適化。{"mode": "standard"} のみ対応
watermarkBoolean右下に「AI 生成」の表示を追加
nsfw_checkBooleanタスク送信前にプロンプトと入力画像を審査

参照画像は jpeg、png、webp、bmp、tiff、gif、heic、heif に対応し、1 枚あたり 30 MB・3,600 万ピクセルまでです。最初の参照画像は無料で、2 枚目以降は 1 枚ごとに固定の追加料金がかかります。

編集箇所を正確に指定したいときは、プロンプトに座標を書きます。1 点なら <point>x y</point>、範囲なら <bbox>x1 y1 x2 y2</bbox> です。

2.3 このモデルが拒否するフィールド

Seedream 5.0 Pro は単一画像モデルです。次のリクエストは 400 を返し、タスクは作成されず、料金もかかりません:

  • n が 1 より大きい、または sequential_image_generation を使う(グループ画像は Seedream 5.0 Lite を使用)
  • stream または tools(ストリーミングと Web 検索は非対応)
  • image_urls が 10 枚を超える
  • 3K や 4K などの非対応ティア、または上記一覧にない比率

2.4 cURL と JavaScript のサンプル呼び出し

1.5K ティアで 16:9 の画像を 1 枚生成する最小限の cURL リクエストです:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "resolution": "1.5K",
    "size": "16:9"
  }'

レスポンスはタスクの受け付けを知らせるだけです:

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

Node.js の fetch で複数参照の編集を行う例です:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedream-5-0-pro",
    prompt: "Replace the outfit in image 1 with the outfit in image 2",
    image_urls: ["https://example.com/person.jpg", "https://example.com/dress.jpg"],
    resolution: "2K",
    size: "auto",
  }),
});

const { data } = await response.json();
const taskId = data[0].task_id;

これらの呼び出しはサーバー側で行い、クライアント側のコードには置かないでください。

3. タスクをポーリングして画像を保存する

3.1 タスクのステータスを確認する

同じ Authorization ヘッダーを付けて GET https://api.apimart.ai/v1/tasks/{task_id} を送ります。Seedream 5.0 Pro は品質優先のため、タスクに数分かかることがあります。5〜10 秒ごとにポーリングし、クライアントのタイムアウトは約 5 分に設定してください。

status が completed または failed になったらポーリングを止めます。失敗したタスクは全額返金されます。

3.2 結果を読み取る

完了したタスクは次のようになります:

{
  "code": 200,
  "data": {
    "id": "task_01JFXYZ123456789ABCDEF",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
          "expires_at": 1784696685
        }
      ]
    }
  }
}

画像は data.result.images[0].url[0] から読み取ります。レスポンスにはタスクの cost も含まれます。リンクの有効期限は 72 時間(expires_at は Unix タイムスタンプ)なので、URL を保存するのではなく、ファイルをダウンロードして自分のストレージに移してください。

3.3 Python によるエンドツーエンドの例

import os
import time

import requests

BASE_URL = "https://api.apimart.ai"
headers = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-pro",
        "prompt": "A product poster with the headline SUMMER SALE in bold letters",
        "resolution": "1.5K",
        "size": "3:4",
        "output_format": "png",
    },
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"][0]["task_id"]

while True:
    task = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=headers, timeout=30).json()["data"]
    if task["status"] == "completed":
        image_url = task["result"]["images"][0]["url"][0]
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", {}).get("message", task["status"]))
    time.sleep(5)

with open("seedream-5-0-pro.png", "wb") as f:
    f.write(requests.get(image_url, timeout=60).content)

4. よく使う 3 つの画像ワークフロー

  • 文字入りのポスターやグラフィック。表示させたい文字をプロンプト内で引用符に入れ、レイアウト(例:「縦長ポスター、見出しは上部」)を説明し、resolution: "1.5K" と 3:4 などの固定比率を使います。2K は料金が高いので、最終成果物のときだけ切り替えます。

  • 複数参照の編集。人物・商品・シーンの画像を image_urls に入れ、プロンプトでは順番で呼びます(「画像 1」「画像 2」)。size: "auto" にすると、出力の比率は参照画像に合わせられます。<bbox> 座標を加えれば、配置場所を正確に指定できます。

  • レイヤー分解と透過編集。PNG または JPEG を 1 枚送り、layer_decomposition: true を指定すると、ベース画像と、位置・重なり順の情報を持つ最大 16 枚の透過 PNG レイヤーが返ります。1 枚のレイヤーだけを編集するには、そのレイヤーを background: "transparent" と output_format: "png" を付けて送り直します。レイヤーのタスクは事前に残高を仮押さえし、完了後に実際の出力枚数で精算します。差額は自動で返金されます。

5. Seedream 5.0 Pro を安定して組み込むための最終チェックリスト

認証とキーの安全性。キーは環境変数またはシークレットマネージャーに置き、API はバックエンドからだけ呼び出します。

送信前にパラメーターを検証する。seedream-5-0-pro を使い、n は省略(または 1)、image_urls は 10 枚以内、1K・1.5K・2K のみを対応する size と組み合わせます。

非同期フローを前提に設計する。5〜10 秒ごとにポーリングし、クライアントのタイムアウトは約 5 分、failed も処理します。

受け取りはストレージの問題として扱う。タスクが成功したらすぐに各画像をダウンロードします。リンクは 72 時間で失効します。

規模を広げる前に費用を確認する。出力はピクセルのティアごとに 1 枚単位で課金され(1K と 1.5K は同じ低い料金、2K は高い)、2 枚目以降の参照画像には追加料金がかかります。大量に実行する前に、最新の料金表を確認してください。

よくある質問

task_id を受け取った後、画像タスクはどう確認すればいいですか?

Authorization: Bearer ヘッダーを付けて GET https://api.apimart.ai/v1/tasks/{task_id} を送ります。

5〜10 秒ごとにポーリングし、status が completed になったら data.result.images[0].url[0] から画像を読み取ります。ステータスが failed の場合は error フィールドを確認してください。失敗したタスクは返金されます。

1 回のリクエストで複数の画像や Base64 の出力を受け取れますか?

できません。Seedream 5.0 Pro は1 回のリクエストで 1 枚の画像を返し、n が 1 より大きいと 400 になります。複数のバリエーションが必要なら複数回リクエストするか、グループ生成に対応した Seedream 5.0 Lite を使ってください。

結果は常に URL で、output_format で jpeg か png を選べます。Base64 は image_urls の入力画像にのみ対応し、出力には使えません。

生成した画像を失わないための最善の方法は?

画像リンクの有効期限は 72 時間で、結果の expires_at で正確な期限がわかります。

タスクが completed になったらすぐに各画像を自分のストレージにダウンロードし、task_id も自分で記録しておきます。返された URL を永続的なストレージとして扱わないでください。

タグ#Seedream 5.0 Pro#画像生成#API チュートリアル#開発者

APIMart チームについて

APIMart チームは、AI でプロダクトを開発する開発者向けに、モデル解説・比較・料金分析を執筆しています。APIMart なら 1 つの API で複数プロバイダーのチャット・画像・動画モデルを利用でき、本記事で紹介したモデルをリリース前に比較検証できます。

次は試してみましょう

モデルマーケットで使いたいモデルを選ぶ

APIMart のモデルマーケットでチャット、画像、動画モデルを試し、統一 API でモデルの能力をすばやく体験できます。

チャットモデル画像モデル動画モデル
モデルマーケットを見る