Seedream 5.0 Pro API

Seevio APIキーを使って、画像の生成、参照画像の編集、画像のレイヤー分解ができます。タスクは非同期で実行されます。taskId を保存し、タスクエンドポイントをポーリングするか、コールバックを受信してください。

POST https://api.seevio.ai/v1/images/generations

対応機能

機能	対応している値
生成モード	`text-to-image, image-to-image, layer-decomposition`
出力解像度	`1K, 1.5K, 2K`
アスペクト比	`1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9`
参照画像	パブリックなHTTPS PNG / JPEG / WebP のURL（1枚あたり最大 30 MB）。Text-to-Imageでは指定なし、Image-to-Imageでは1〜10枚、レイヤー分解では正確に1枚の画像を指定します。
プロンプト	前後の空白を除いた長さが4〜5,000文字のプロンプトを指定してください。layer-decomposition の場合に限り、prompt は省略するか空にできます。
出力形式	`png, jpg`

料金とクレジット

以下の価格は返された画像1枚あたりの単価です。通常の生成では画像1枚分が事前予約されます。レイヤー分解では画像17枚分が一時的に予約され、実際に返された枚数（ベース画像含む）に応じて最終決済が行われ、未使用分のクレジットは元の残高へ返還されます。失敗したタスクは全額返金されます。

出力解像度	料金とクレジット
1K	4 クレジット
1.5K	4 クレジット
2K	8 クレジット

デフォルトの 2K 解像度の場合、レイヤー分解では最初に 136 クレジットが予約されます。最終的に4枚の画像が返された場合、確定請求額は 32 クレジットとなり、差額の 104 クレジットが返還されます。

リクエストのべき等性はサポートされていません。有効な POST リクエストを送信するたびに、課金対象となる新しいタスクが作成されます。送信結果が不明な場合は、返された taskId をクエリして確認してください。POST リクエストを再試行すると、別のタスクが作成される可能性があります。

認証

ダッシュボードでAPIキーを作成してください。APIキーの全体が表示されるのは作成時の1回のみです。キーは安全なサーバー上で管理し、すべてのリクエストのヘッダーに Bearer トークンとして含めて送信してください。

APIキーを作成 APIダッシュボード

ベースURL

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

これらのサンプルコードを実行する前に、環境変数 SEEVIO_API_KEY を設定してください。JavaScriptのサンプルはサーバー上の Node.js で、Pythonのサンプルは requests ライブラリを使用して実行します。

リクエストボディ

フィールド	データ型	必須	説明と制約条件
`model`	string	はい	モデルID。Seedream 5.0 Proを使用するには、このフィールドをseedream-5-0-proに設定してください。
`callback_url`	string	いいえ	タスク完了時または失敗時に POST コールバックを受け取るための、一般公開されている HTTPS エンドポイント。プライベートネットワークや localhost は指定できません。例: `https://example.com/webhooks/seevio`
`input`	object	はい	生成の設定。Text-to-ImageおよびImage-to-Imageではプロンプトが必須ですが、レイヤー分解では任意です。

入力パラメータ

フィールド	データ型	必須	デフォルト値	説明と制約条件
`input.prompt`	string	条件付き	`—`	前後の空白を除いた長さが4〜5,000文字のプロンプトを指定してください。layer-decomposition の場合に限り、prompt は省略するか空にできます。例: `A minimalist ceramic teapot on a stone pedestal, soft studio lighting`
`input.generation_type`	string	いいえ	`text-to-image`	新しい画像を生成する場合は text-to-image、参照画像を編集する場合は image-to-image、単一の画像を再利用可能な構成要素に切り分ける場合は layer-decomposition を使用します。対応している値 `text-to-image \| image-to-image \| layer-decomposition`
`input.image_urls`	string[]	条件付き	`[]`	パブリックなHTTPS PNG / JPEG / WebP のURL（1枚あたり最大 30 MB）。Text-to-Imageでは指定なし、Image-to-Imageでは1〜10枚、レイヤー分解では正確に1枚の画像を指定します。例: `["https://example.com/teapot.png"]`
`input.aspect_ratio`	string	いいえ	`1:1`	アスペクト比対応している値 `1:1 \| 4:3 \| 3:4 \| 16:9 \| 9:16 \| 2:3 \| 3:2 \| 21:9` 例: `1:1`
`input.resolution`	string	いいえ	`2K`	Text-to-Image および Image-to-Image は 1K（標準画質）および 2K（高画質）に対応しています。レイヤー分解は 1K、1.5K、2K に対応しています。デフォルト：2K。対応している値 `1K \| 1.5K \| 2K` 例: `2K`
`input.output_format`	string	いいえ	`png`	リクエストする出力フォーマット。レイヤー分解の場合、pngはPNG形式のベース画像を、jpgはJPEG形式のベース画像を返します。分割されたレイヤーはすべて、透明度が維持されたPNG形式で返されます。対応している値 `png \| jpg` 例: `png`

1回のリクエストにつき、1つのタスクが作成されます。テキストから画像（Text-to-image）および画像から画像（Image-to-image）の生成では1枚の画像が返されます。レイヤー分解（layer-decomposition）では、ベース画像を含む1〜17枚の画像が返されます。レイヤー分解を使用する場合は、aspect_ratio を送信しないでください。

クイックスタート

この最小限のリクエストを送信し、返された taskId を保存した上で、後述のタスクステータス確認の例を実行してください。作成レスポンスに含まれる credits の値は、確保（仮売上）されたクレジット量を示しています。

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

タスク作成時のレスポンス例

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

テキストから画像を生成

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

画像から画像を生成

画像編集を行う場合は、generation_type を image-to-image に設定し、image_urls を指定してください。その他のパラメータはすべて共通の仕様が適用されます。

example.com のメディアURLは、ご自身でホストしている公開済みの HTTPS ファイルのURLに置き換えてください。サンプルのURLはリクエストの構造を示すためのものであり、ダウンロード可能なアセットではありません。

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

レイヤー分解

generation_typeをlayer-decompositionに設定し、画像URLを1つだけ指定してください。aspect_ratioは省略してください。output_formatはベース画像のフォーマットのみを制御します。分割されたレイヤーは、常に透明度が維持されたPNG形式で返されます。data.results に含まれるすべてのURLを保存してください。

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

レイヤー分解では、ベース画像と分離された各レイヤーを含む複数の画像URLが data.results に返される場合があります。それぞれのURLは独立した画像を指しています。結果の枚数はタスクによって異なります（合計 1〜17 枚）。data.results[0] のみを参照するのではなく、配列全体を処理してください。完了時のタスク照会および完了コールバックの両方にこの配列が含まれます。最初のタスク作成レスポンスに含まれるのは taskId と予約クレジットのみであり、画像URLは含まれません。

タスク作成時のレスポンス例

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

レイヤー分解完了：複数の画像URLのレスポンス例

このレスポンス例には、1枚のベース画像と3枚のレイヤーという計4枚の出力画像が含まれています。実際のタスクで返される枚数は異なる場合があります。リクエストされた 2K 解像度において、credits の値は4枚すべてに対する最終請求額であり、最初に17枚分として予約されていたクレジットの未使用分はすでに返還されています。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

返されたすべての画像を処理する

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

タスクのステータス確認

GET https://api.seevio.ai/v1/tasks/{taskId}

サンプルのIDを、作成時に返された taskId に置き換えてください。ステータス確認は、そのAPIキーを所有するユーザーのタスクのみ可能です。権限がない、または存在しないIDの場合は HTTP 404 が返されます。

最初は10〜20秒間隔でポーリングを開始し、HTTP 429（レートリミット）が発生した場合は間隔を空け、ステータスが completed または failed になったら終了します。本番環境ではウェブフックの使用を推奨します。以下の各コード例は、1回のステータス確認リクエストを行うものです。

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

ステータス	許容される値と要件
queued	受け付けられ、処理待ちの状態です。
generating	画像を生成中です。
completed	生成成功（最終状態）。有効期限が切れる前に data.results から画像をダウンロードしてください。
failed	生成失敗（最終状態）。failed_reason と billing_status を確認してください。

フィールド	データ型	許容される値と要件
id	string	タスク識別子。作成時のレスポンスに含まれる taskId と同一です。
created_at	number	Unixタイムスタンプ（秒）で表されるタスク作成日時。
model	string	このタスクに使用された公開モデルのID。
billing_status	string	reserved（仮確保）、charged（決済完了）、refunded（返金済み）、または refund_failed（返金失敗）。
credits	number	作成時のレスポンスおよび処理中タスクには予約クレジットが表示されます。完了時、credits の値は実際に引き落とされた確定額を示し、未使用の予約分は既に返還されています。失敗したタスクには最初に予約された額が表示され続けます。
failed_reason	string \| null	タスクが失敗した場合のエラー理由。それ以外は null。ステータス確認時にタスクが失敗している場合、レスポンスに data は含まれません。
failed_code	string \| null	エラーコード。詳細は failed_reason を参照してください。
data	object	タスクが失敗していない場合に返されます。出力結果と処理の詳細が含まれます。
data.results	string[]	出力されたすべての画像URL。レイヤー分解の場合はベース画像も含まれます。タスク完了前や有効期限切れの後は空になります。
data.image_expires_at	string \| null	画像の有効期限（ISO 8601）。未確定の場合は null。
data.processing_time	number \| null	タスクの処理時間（秒単位）。取得できない場合は null となります。

待機中

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

完了

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

失敗

クエリのレスポンスとしてstatus=failedが返された場合は、画像生成が正常に終了しなかったことを意味します。失敗の理由はfailed_reasonで、返金結果はbilling_statusで確認できます。この例では、refundedとなっておりクレジットが返却されたことを示しています。creditsには最初に確保された額がそのまま表示され、レスポンスにdataは含まれません。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

生成結果のリンクは保存後30日間有効です。期限が切れると、results は空になります。

ウェブフック

作成リクエスト時に callback_url を設定すると、タスクが完了または失敗した際、JSONデータが POST リクエストで送信されます。受信側は15秒以内に 2xx レスポンスを返してください。配信に失敗した場合は再試行されます。同一のタスクIDで重複してコールバックを受信することがあるため、冪等（べきとう）な処理を行ってください。

コールバックエンドポイントは、JSON形式のリクエストボディ（Content-Type: application/json）を含むPOSTリクエストを受け付ける必要があります。

コールバックを指定してタスクを作成

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

コールバックにはタスククエリのレスポンス構造が使用されます。返金が発生した失敗通知には、トップレベルに credits_refunded も含まれます。タスクの特定には id を、完了と失敗の判別には status を使用してください。通知は重複して送信される場合があるため、id と status に基づいてべき等（重複排除）に処理してください。コールバックは署名されません。タスクの検証は、認証済みのクエリ処理エンドポイントを使用して行ってください。コールバックの配信に失敗した場合でも、成功したタスクの返金は行われません。

タスク完了：処理成功時のコールバックペイロード

created_at はイベント作成時刻、task_created_at はタスク作成時刻で、どちらも Unix 秒です。例では推奨フィールドを示しています。応答には追加フィールドが含まれる場合があります。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

タスク失敗：処理失敗時のコールバックペイロード

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

レシーバーの実装例

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

このNext.jsのサンプルコードは、JSON形式のコールバックボディを読み込み、成功したタスクと失敗したタスクを直接処理します。実際のアプリケーション開発では、永続化処理やタスクIDの重複排除を追加してください。また、時間のかかる処理はキューに登録してから、コールバックへの応答を返すようにしてください。

エラー

HTTPエラーは、code と message を含む error オブジェクトを返します。正常に受け付けられたタスクであっても後から失敗することがあるため、タスクのステータスを確認するか、失敗時のコールバックを適切に処理してください。

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	フィールド	対処方法
400	`invalid_request`	JSONの構文、プロンプトの有無、パラメータの範囲、またはメディアURLに問題があります。修正して再試行してください。
401	`invalid_api_key`	Bearer トークンが正しいか、およびAPIキーが有効化されているかを確認してください。
402	`insufficient_credits`	クレジットを追加するか、タスクの消費想定を減らしてください。レスポンスには、必要なクレジット数と現在の保有クレジット数が含まれる場合があります。
403	`forbidden`	エラーメッセージに記載されているアカウントレベルの制限事項を確認してください。
404	`not_found`	タスクIDが正しいか、およびそのキーがタスクの作成者と一致しているかを確認してください。
429	`rate_limited`	Retry-After ヘッダーに示された秒数が経過した後に再試行してください。
500	`internal_error`	エラーメッセージとAPIログを確認してください。注意深く再試行してください。作成リクエストを再送信すると、新たに課金対象となるタスクが作成される可能性があります。

エラー時には error.code と error.message が返されます：400 invalid_request、401 invalid_api_key、402 insufficient_credits、403 forbidden、404 not_found、429 rate_limited、500 internal_error。402 insufficient_credits エラーは、このリクエストを実行するためのクレジット残高が不足していることを意味します。

レートリミット

タスクの作成：デフォルトでは、APIキー1つにつき1分あたり最大100回のリクエストが可能です。現在、カスタムレート制限の設定はご利用いただけません。

タスクの照会：デフォルトでは、APIキー1つにつき1分あたり最大120回のリクエストが可能です。照会リクエストとタスク作成リクエストは別々にカウントされます。

画像生成と動画生成のリクエストは、同一の API キーのレート制限を共有します。

HTTP 429 レスポンスの Retry-After は、タスク作成時には 60、タスク確認時には 5 が設定されます。エクスポネンシャルバックオフなどの仕組みを導入し、必要以上の頻度でポーリングを行わないようにしてください。

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}