Seedream API

このプラットフォームでは、公開モデル ID seedream-4-5、seedream-5-0-lite、seedream-5-0-pro 向けに非同期の画像生成エンドポイントを提供しています。

このドキュメントはクライアント実装者向けに、公開リクエストパス、認証、リクエストパラメーター、タスク結果のレスポンス契約を説明します。

概要:

タスク作成: POST /v1/images/create
タスク照会: GET /v1/tasks/{task_id}
モデル ID: seedream-4-5, seedream-5-0-lite, seedream-5-0-pro
実行方式: 非同期タスク
主な用途: テキストから画像、画像編集、連続画像生成
入力画像: input.image_urls による URL 入力のみ

1. 概要

リクエストメソッド: POST
リクエストパス: /v1/images/create
Content-Type: application/json
結果の取得方法:
- 作成 API はタスクの受理結果のみを返します
- 最終結果は /v1/tasks/{task_id} をポーリングするか、callback_url で受け取ります

2. 認証

リクエストヘッダー:

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

ヘッダー	必須	説明
`Authorization`	はい	`Bearer sk-xxxxxx` 形式のプラットフォーム API キー
`Content-Type`	はい	`application/json` 固定

3. タスク作成

リクエストボディ例:

{
  "model": "seedream-5-0-pro",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A premium product hero image, square composition, clean studio lighting",
    "image_urls": [],
    "resolution": "2k",
    "output_format": "png",
    "watermark": false,
    "sequential_image_generation": "disabled"
  }
}

3.1 トップレベルパラメーター

フィールド	型	必須	説明
`model`	string	はい	`seedream-4-5`、`seedream-5-0-lite`、`seedream-5-0-pro` のいずれかを指定します
`callback_url`	string	いいえ	終了状態のコールバック URL。`https` のみ対応。最大長は `2048`。ローカル、イントラネット、プライベートネットワーク宛先は拒否されます
`input`	object	はい	画像生成パラメーター

3.2 `input` パラメーター

フィールド	型	必須	説明
`prompt`	string	はい	生成プロンプト。比率、構図、用途が必要な場合はプロンプトに含めます
`image_urls`	`array<string>`	いいえ	参照画像 URL のリスト。省略または空配列の場合はテキストから画像、1 件以上の場合は画像編集です。`seedream-5-0-pro` は最大 10 枚、ほかのモデルは最大 14 枚
`resolution`	string	いいえ	出力解像度。`seedream-4-5` は `2k`, `4k`、`seedream-5-0-lite` は `2k`, `3k`, `4k`、`seedream-5-0-pro` は `1k`, `2k` に対応し、既定値は `2k`
`size`	string	いいえ	出力サイズ。`resolution` より優先されます。モデル対応の解像度または `2048x2048`, `3750x1250` などのピクセルサイズを指定できます
`output_format`	string	いいえ	`seedream-5-0-lite` と `seedream-5-0-pro` が対応。値は `png`, `jpeg`。`seedream-4-5` はこのフィールド非対応で、既定では JPEG を出力します
`watermark`	boolean	いいえ	上流ウォーターマークを追加するかどうか。省略時は上流の既定値に従います
`sequential_image_generation`	string	いいえ	連続画像生成を有効にするかどうか。値は `auto`, `disabled`。省略時は上流既定の `disabled`
`sequential_image_generation_options`	object	いいえ	連続画像生成オプション。`sequential_image_generation` が `auto` の場合のみ有効
`optimize_prompt_options`	object	いいえ	プロンプト最適化オプション。`seedream-5-0-pro` は `standard` と `fast`、ほかのモデルは `standard` のみに対応

sequential_image_generation_options:

フィールド	型	必須	説明
`max_images`	integer	いいえ	このタスクで生成する最大画像数。`sequential_image_generation` が `auto` の場合、`1` から `15`。参照画像数と `max_images` の合計は `15` 以下

optimize_prompt_options:

フィールド	型	必須	説明
`mode`	string	いいえ	プロンプト最適化モード。`standard` は品質を重視する既定値です。`fast` は品質がわずかに下がる可能性と引き換えに待ち時間を短縮し、`seedream-5-0-pro` のみ対応します

補足:

Seedream は input.aspect_ratio に対応していません。比率指定はプロンプトに含めるか、input.size を直接指定してください。
プラットフォームは常に非同期タスクフローを使用します。
タスク結果の主契約は data[].url です。
ローカル画像は先に POST /v1/images/uploads でアップロードし、返された URL を input.image_urls に渡してください。
Pro の上流モデルが Base64 を直接サポートしていても、Base64 画像入力は ReachAPI の公開契約には含まれません。

4. リクエスト例

4.1 テキストから画像

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4-5",
    "input": {
      "prompt": "A quiet ceramic tea cup on a wooden table, square composition, soft morning light",
      "resolution": "2k",
      "watermark": false
    }
  }'

4.2 出力形式を指定するテキストから画像

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "A premium skincare bottle hero image, 4:5 vertical poster composition, clean studio lighting",
      "resolution": "3k",
      "output_format": "png",
      "watermark": false
    }
  }'

4.3 画像編集

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4-5",
    "input": {
      "prompt": "Turn this sneaker photo into a clean e-commerce hero image, keep the original product shape",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "2k"
    }
  }'

4.4 カスタムサイズ

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "A wide cinematic concept art image for a sci-fi city skyline",
      "size": "3750x1250",
      "output_format": "jpeg"
    }
  }'

4.5 連続画像生成

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "Create a coherent set of 4 product lifestyle images for the same perfume bottle",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "2k",
      "sequential_image_generation": "auto",
      "sequential_image_generation_options": {
        "max_images": 4
      }
    }
  }'

4.6 プロンプト最適化

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "A restaurant poster for a summer tasting menu",
      "resolution": "2k",
      "optimize_prompt_options": {
        "mode": "fast"
      }
    }
  }'

4.7 Seedream 5.0 Pro インタラクティブ編集

seedream-5-0-pro は、入力画像上の手描きマークを自然言語で説明して局所的な編集領域を指定できます。より正確に配置する場合は、プロンプト内で <point> または <bbox> 座標タグを使用します。

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "画像 2 の <bbox>118 331 933 871</bbox> にある被写体を使い、画像 1 の <bbox>179 283 796 986</bbox> にある被写体を置き換えてください。",
      "image_urls": [
        "https://cdn.example.com/base-image.png",
        "https://cdn.example.com/subject-reference.png"
      ],
      "resolution": "2k",
      "output_format": "png",
      "watermark": false
    }
  }'

座標タグは編集領域と配置先を示すものであり、image_urls の代わりにはなりません。プロンプトで参照する順序と同じ順序で画像を渡してください。

5. 作成レスポンス

レスポンス例:

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

フィールド	型	説明
`code`	integer	プラットフォームの業務ステータスコード
`msg`	string	エラーまたは状態メッセージ
`status`	string	初期タスク状態。通常は `queued`
`task_id`	string	後続の照会に使うタスク ID
`data`	array	タスク作成時は空配列

6. タスク照会

リクエスト例:

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY"

状態:

状態	説明
`queued`	受理済み、実行待ち
`generating`	生成中
`success`	生成成功
`failed`	生成失敗

成功レスポンス例:

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/image-1.jpeg"
    }
  ]
}

失敗レスポンス例:

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

補足:

主なレスポンス契約は data[].url です。
連続画像生成では、data[] に複数の画像が返る場合があります。
一部の画像がフィルタリングまたは生成失敗した場合、成功した画像のみ返します。成功画像が 1 枚もない場合、タスクは失敗します。

7. コールバック

タスク作成時に callback_url を指定すると、タスクが終了状態になったときにゲートウェイがその URL へ POST リクエストを送信します。コールバック body はタスク照会レスポンスと同じ構造です。

コールバック制約:

https URL のみ対応
最大長は 2048
localhost、.local、明らかなプライベートネットワーク宛先は拒否されます
1 回の送信タイムアウトは 10s
失敗時は最大 2 回再試行し、合計最大 3 回送信します

8. 制約と非対応フィールド

prompt は必須で、空にはできません
seedream-5-0-pro の image_urls は最大 10 枚、seedream-4-5 と seedream-5-0-lite は最大 14 枚
image_urls はサーバーからアクセス可能な https URL である必要があります
seedream-5-0-pro の入力形式は jpeg, png, webp, bmp, tiff, gif, heic, heif に対応します
Pro の入力画像 1 枚ごとの制限: 30MB 以下、幅と高さはいずれも 14px より大きいこと、アスペクト比は 1/16 から 16、総ピクセル数は 36,000,000（6000x6000）以下
seedream-4-5 の resolution: 2k, 4k
seedream-5-0-lite の resolution: 2k, 3k, 4k
seedream-5-0-pro の resolution: 1k, 2k。既定値は 2k
size はモデル対応の解像度または <width>x<height> 形式のピクセルサイズを指定できます
seedream-5-0-pro のカスタムピクセル size は、総ピクセル数が 921,600（1280x720）から 4,624,220（2048x2048x1.1025）、アスペクト比が 1/16 から 16 の範囲である必要があります
seedream-4-5 と seedream-5-0-lite のカスタムピクセル size は、総ピクセル数が 2560x1440 から 4096x4096、アスペクト比が 1/16 から 16 の範囲である必要があります
sequential_image_generation は auto, disabled のみ
seedream-5-0-pro の optimize_prompt_options.mode は standard, fast、ほかのモデルは standard のみ
seedream-5-0-pro のインタラクティブ編集では、prompt 内の手描きマークおよび <point> / <bbox> 座標タグを使用できます
上流で生成された画像 URL の保持期間は 24 時間です。速やかにダウンロードまたは永続保存してください
watermark は boolean である必要があります

公開入力フィールドとして非対応:

input.image_base64s
画像入力フィールド内の Base64 画像データ
input.aspect_ratio
input.system_prompt
input.enable_web_search
input.stream
input.response_format
input.seed
input.guidance_scale
input.n
input.quality
input.background
input.moderation
input.negative_prompt

Seedream API

On this page