このページの内容
Seedream API：Seedream 5.0 Pro
Seedream APIでSeedream 5.0 Proを利用し、テキストプロンプトまたは最大10枚の公開HTTPS参照画像から1枚の画像を生成できます。ImyaがAPI認証、非同期タスク、リアルタイムのクレジット課金、安全化されたエラー、結果保存を管理します。
REST API · v1 · 非同期タスク
構築できるもの
プロンプトからの生成、参照画像を使ったバリエーション、自動画像生成を1つのRESTワークフローで実装できます。
商品・キャンペーン画像
テキストプロンプトから商品シーン、広告コンセプト、ブランドビジュアルを生成します。
参照画像を使ったバリエーション
1〜10枚の参照画像で、新しい結果の被写体、構図、視覚的な方向性を指定します。
自動画像生成ワークフロー
非同期で送信し、公開task IDを取得して、Imya管理ストレージから完成画像を受け取ります。
最初のSeedream APIリクエストを送信する
タスクを作成して公開task IDを保存し、成功または失敗になるまでタスクを取得します。
- 1
APIキーを作成
Imyaアカウントの設定画面でキーを発行します。
- 2
入力を選択
プロンプトのみ、または1〜10枚の参照画像を追加します。
- 3
結果を取得
公開task IDを5秒以上の間隔で取得します。
認証と冪等性
Imya APIキーをBearerトークンとして送信します。生成POSTには一意のIdempotency-Keyも必須です。ネットワーク再試行で別のタスク作成や二重課金は発生しません。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY画像生成タスクを作成
テキスト画像生成ではimage_urlsを省略します。参照画像生成では1〜10枚の公開HTTPS画像を追加します。サーバーはこのリクエストのcredits_reservedをリアルタイムで返します。
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-product-shot-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "A premium skincare bottle on pale stone, soft morning light",
"aspect_ratio": "4:3",
"quality": "basic",
"output_format": "png",
"n": 1
}'curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-edit-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "Keep the product shape and place it in a warm studio",
"image_urls": ["https://cdn.example.com/input/product.png"],
"aspect_ratio": "4:3",
"quality": "high",
"output_format": "jpeg",
"n": 1
}'タスクを取得
最新の状態、最終クレジット使用量、保存済み画像、または安全化されたエラーを返します。取得間隔は5秒以上にしてください。短い間隔のリクエストもレート制限に数えられますが、上流の状態は更新されません。
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"リクエストパラメーター
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| model | string | はい | seedream-5-proを指定します。 |
| prompt | string | はい | 3〜3,000文字の生成指示です。 |
| image_urls | string[] | いいえ | 公開HTTPS参照画像を1〜10枚指定します。テキスト画像生成では省略します。 |
| aspect_ratio | string | いいえ | 1:1、4:3、3:4、16:9、9:16、2:3、3:2のいずれかです。既定値は1:1です。 |
| quality | string | いいえ | basicまたはhigh。既定値はbasicです。16:9と9:16はbasicのみ対応します。 |
| output_format | string | いいえ | pngまたはjpeg。既定値はpngです。 |
| n | number | いいえ | 1のみ指定できます。生成画像は常に1枚です。 |
レスポンス
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:38.000Z",
"credits_reserved": 44,
"credits_used": 44,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}新規タスクはHTTP 202を返します。同一内容の冪等な再送はHTTP 200とIdempotent-Replayed: trueを返します。成功画像はタスクがsucceededになる前にImya管理ストレージへコピーされます。失敗タスクではgeneration_failed、refund_pending、media_deletedが返る場合があります。
リアルタイムのクレジット課金
basicとhighの基本料金はいずれも35クレジットです。サーバーがAPIキー所有者の現在のプラン係数を適用します。例では通常アカウントに1.25倍を適用し、44クレジットに丸めています。常にレスポンスのcredits_reservedを使用してください。タスクが30分以内に完了しない場合、Imyaは失敗として処理し、対象クレジットを1回だけ返却します。元の有効期限は延長されません。
クレジットプランを見るタスクステータス
pendingタスクを受け付け、開始を待っています。
processingモデルが画像を生成しています。
succeeded生成が完了し、dataに保存済み画像が含まれます。
failed生成に失敗しました。安全化されたerrorオブジェクトを確認してください。
エラー
400Idempotency-Keyがないか、JSONの形式が不正です。
401APIキーがないか、無効です。
402アカウントのクレジットが不足しています。
403APIアカウントが無効か、このリクエストは許可されていません。
404タスクが存在しないか、このアカウントに属していません。
409同じ冪等キーが異なるリクエスト本文で再利用されました。
413リクエスト本文が64 KiBを超えています。
415Content-Type は application/json である必要があります。
422モデルパラメーター、プロンプト、または参照画像が無効です。
429APIキーのレート制限または同時実行数の上限に達しました。
5xxリクエストを完了できませんでした。新規作成前に元のタスクを確認してください。
Imya 公開 API の共通仕様
以下のルールは、すべての公開画像・動画生成 API に適用されます。モデル固有のパラメータと料金は、このページのパラメータ表を確認してください。
課金と安全な再試行
新しいタスクが受理されると、credits_reserved に表示された正確なクレジットがアトミックに差し引かれます。同じ Idempotency-Key と同じリクエスト本文を再送しても、二重課金されません。
タイムアウトと返金
30 分以内に最終状態へ到達しないタスクは失敗になります。対象クレジットの返金は一度だけ行われ、元の有効期限が維持されます。
レートと同時実行制限
API キーごとに 60 秒間で最大 120 リクエストです。同一アカウントでは画像タスクを最大 5 件、動画タスクを最大 3 件まで同時実行できます。429 応答には Retry-After が含まれる場合があるため、返された場合は従ってください。
ポーリングと所有権
タスク作成時に返された id を使い、GET /v1/tasks/{id} を 5 秒以上の間隔で取得してください。短い間隔のリクエストも API キーのレート制限に数えられますが、上流の状態は更新されません。作成したアカウントだけが結果を参照でき、現在は Webhook、SDK、バッチ送信に対応していません。
エラーとコンテンツ安全性
公開エラーはサニタイズされ、上流の認証情報、内部 URL、インフラ情報を公開しません。安全でないプロンプトは生成前に prompt_blocked で拒否される場合があります。
画像結果の保存期間
無料アカウントの画像結果は 7 日間、有効な有料プランまたは Lifetime アカウントでは最長 30 日間保存されます。削除後は空の成功応答ではなく、status が failed、error.code が media_deleted の応答を返します。
Seedream API 本番環境導入ガイド
安定した Seedream 5.0 Pro 連携は、1 回の長時間 HTTP リクエストではなく、小規模な非同期ジョブシステムとして設計します。モデルの選択肢を設定に集約し、Imya タスクから返される id を必ず保存し、再試行を決定的にしてください。以下はローカルのサンプルから本番環境へ進む際の実践的な指針です。
モデル仕様からパラメーターを選ぶ
送信前に、このページのパラメーター表に対してすべてのリクエストを検証します。開発中は最小のサポート済み入出力から始め、製品に必要な場合にだけ品質、サイズ、長さ、または参照数を増やします。ユーザー入力のプロンプトとファイルは、API を呼び出す前に長さ、種類、容量を自社サーバーで確認してください。
参照画像を使う場合は順序を保ち、ユーザーがすべてのアップロード画像を使用できる権利を持つことを確認します。
復旧できる非同期フローを設計する
画像タスクを送信し、返却された id を自社のジョブレコードと共に保存し、バックグラウンドワーカーで状態を取得します。GET /v1/tasks/{id} は 5 秒以上の間隔でポーリングしてください。短い間隔のリクエストも API キーのレート制限に数えられますが、上流の状態は更新されません。公開 status は pending、processing、succeeded、failed の 4 種類だけです。タスクのハード期限は 30 分です。最終状態を受信するか期限に達したら停止します。現在、Webhook、SDK、バッチ送信は利用できないため、HTTP リクエストとポーリングで連携します。
- 01UI を更新する前に、id、status、credits_reserved、リクエスト識別子を永続化します。
- 02一時的なネットワークエラーではバックオフし、429 の Retry-After に従い、通信エラーから新しい有料タスクを自動作成しないでください。
- 03同一アカウントの同時実行は最大 5 件の画像タスクです。API キーごとに 60 秒間で最大 120 リクエストです。
課金と再試行を決定的にする
新しいタスクが受理されると、credits_reserved で返された正確なクレジットがアトミックに差し引かれます。意図した作成ごとに 1 つの Idempotency-Key を生成し、リクエストと一緒に保存します。同じ Key と同じ本文の再送は元のタスクを返し、二重課金されません。リクエストを変更した場合は新しい Key を使います。
失敗タスクが返金対象の場合、Imya はクレジットを一度だけ返し、元の有効期限を維持します。公開 status は failed のままで、決済処理中は error.code が refund_pending、返金完了後は credits_refunded が応答に含まれます。id で照合し、クライアント側でクレジットを発行しないでください。
認証情報、所有権、生成メディアを保護する
API キーはサーバーに保存し、ブラウザーやモバイルバンドルに埋め込まないでください。返された各 id を作成者の認証済みユーザーまたはワークスペースに関連付け、結果を表示する前に確認します。公開エラーはサニタイズされています。サポート用に独自のリクエスト ID とタスク id を記録し、プロンプト、非公開 URL、認証情報は露出しないでください。
画像結果は無料アカウントで 7 日間、有効な有料プランまたは Lifetime アカウントで最長 30 日間利用できます。削除後は応答の status が failed、error.code が media_deleted になります。製品で保存が必要な結果は、ユーザーの同意と自社のプライバシーポリシーに従って、自社管理のストレージに複製してください。
本番環境チェックリスト
- 送信前にモデル固有のフィールドを検証する。
- 意図したタスクごとに Idempotency-Key とリクエスト本文を保存する。
- タスク状態を永続化し、5 秒以上の間隔でポーリングする。
- アカウントの同時実行数と API キーのレート制限を実施する。
- 4 種類の公開 status を明示的に処理する。failed では error.code の media_deleted または refund_pending を確認し、credits_refunded で返金完了を確認する。
- 認証情報をサーバー側に保ち、結果の保存ポリシーを定義する。
よくある質問
ワーカーはどのくらいの間隔でポーリングすべきですか？
5 秒以上の間隔にします。処理中のタスクには、バックオフを伴うより遅いポーリングも適切です。
クレジットはいつ差し引かれますか？
新しいタスクが受理された時点で、credits_reserved の正確な額がアトミックに差し引かれます。
再試行で二重課金されますか？
同じ Idempotency-Key と完全に同じリクエスト本文の再送は、元のタスクを返し、再課金されません。
タスクが最終的に失敗したらどうしますか？
明確な製品向けエラーを表示し、サポート用に id を保持し、対象となる 1 回限りの返金はサーバーに完了させます。存在しない refunded status を待たず、credits_refunded で結果を確認します。
実装を始めますか？
最初のリクエスト用にImya APIキーを作成するか、実装前にオンライン生成ツールでプロンプト、参照画像、品質設定を試せます。