# Seedream 5.5 — /images/generations

Seedream 5.5（Beta）の画像生成 API です。ByteDance の最新世代 Seedream 画像モデルで、テキストから画像・編集・複数画像の合成を 1 つのモデルで行い、非同期タスクとして動きます。送信するとすぐにタスク ID が返り（HTTP 202）、その後ポーリングで結果を取得するか、Webhook で受け取ります。1K と 2K・9 種類の比率で、PNG オリジナルを納品します。1 枚ごとの課金、失敗した場合は課金されません。Beta 期間中は混雑時に失敗したり遅くなったりすることがあります。その場合はそのまま再送信してください。

**エンドポイント:** `POST https://kovapi.com/v1/images/generations`

## クイックスタート

3 ステップで動きます：タスクを送信 → 結果を照会 → 画像のリンクを受け取る。YOUR_API_KEY をご自身のキーに置き換えれば、下のコマンドはそのまま実行できます。

**ステップ 1 · タスクを送信（すぐにタスク ID が返ります。HTTP 202）**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.5", "prompt": "夕暮れの路地にあるカフェの入口、黒板にチョークで「本日のおすすめ：金木犀ラテ 480円」、そばに茶トラの猫、写実的な写真", "size": "16:9", "resolution": "2K"}'
```

レスポンス（HTTP 202）

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedream-5.5"
}
```

**ステップ 2 · `status` が `succeeded` か `failed` になるまで、2〜3 秒ごとに照会**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功時のレスポンス

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedream-5.5",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "seedream-5.5"}
}
```

**ステップ 3 · `data[0].url` が画像（PNG オリジナル）のリンクです。保存期間は 7 日間なので、長く使う場合はご自身のストレージにダウンロードしてください。**

**完全なサンプル（Python：送信 → 待機 → ローカルに保存）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. タスクを送信
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "seedream-5.5",
    "prompt": "夕暮れの路地にあるカフェの入口、黒板にチョークで「本日のおすすめ：金木犀ラテ 480円」、そばに茶トラの猫、写実的な写真",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 終わるまで 3 秒ごとに照会
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 画像をダウンロード
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedream-5.5.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## 認証
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## リクエストパラメータ

`POST /v1/images/generations` のリクエスト本文（JSON）：

| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| model | string | はい | モデル ID：`seedream-5.5`。 |
| prompt | string | はい | 描きたい内容。画像から画像の場合は、どう変えるかを書きます。 |
| size | string | いいえ | 比率：`1:1`（既定）、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`、`9:21`。ピクセルサイズ（例 `2560x1440`）も指定でき、比率で上の 9 種類のどれかに合わせます。それ以外の比率は送信時に 400 を返し、課金されません。納品はその比率のネイティブサイズです（ドキュメントのサイズ表を参照）。 |
| resolution | string | いいえ | グレード：`1K`（既定）または `2K`。4K はありません。 |
| image / images | string / array | いいえ | 参照画像。指定すると編集・合成になります。1 枚は `image`、複数は `images`（最大 10 枚）。公開画像の URL・data: URI・base64 が使えます。複数のときは順番どおりに各画像の使い方をプロンプトに書いてください（例：「画像 1 の人物が画像 2 のカフェに座っている」）。 |
| n | integer | いいえ | 常に 1：1 回 1 枚です。複数ほしいときは複数のジョブを同時に送ってください。ほかの値は送信時に 400 を返し、課金されません。 |
| callback_url | string | いいえ | タスク終了時に結果を送る先。下の Webhook の項目をご覧ください。 |

その他の OpenAI パラメータ（`quality`、`background`、`output_format`、`style` など）には対応していません。指定しても効果はなく、料金も変わりません。成果物は常に PNG オリジナルで、`url` で返します。`response_format: "b64_json"` を指定すると結果に base64 も付きます。

## 料金

1 枚ごとの課金で、料金はグレードだけで決まります。比率や、テキストから画像か画像から画像かは関係ありません。送信時にそのグレードの料金を確保し、タスクが失敗した場合は全額返金します。1 クレジット = $0.005 です。

| グレード | 1 枚あたりのクレジット | 1 枚あたりの料金（USD） |
| --- | --- | --- |
| 1K | 4 | $0.02 |
| 2K | 6 | $0.03 |

## 比率・解像度・出力サイズ

`size` に比率、`resolution` にグレードを指定します。モデルがその比率で描いたオリジナルを納品し、比率とグレードごとのサイズは下表のとおり固定です。切り抜き・リサイズはしません。

| 比率 | 1K | 2K |
| --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 |
| 16:9 | 1424x800 | 2816x1584 |
| 9:16 | 800x1424 | 1584x2816 |
| 4:3 | 1152x864 | 2368x1776 |
| 3:4 | 864x1152 | 1776x2368 |
| 3:2 | 1248x832 | 2496x1664 |
| 2:3 | 832x1248 | 1664x2496 |
| 21:9 | 1568x672 | 3136x1344 |
| 9:21 | 672x1568 | 1344x3136 |

- 対応する比率は表の 9 種類だけで、それ以外（5:4、2:1 など）は送信時に 400 `unsupported_size` を返し、課金されません。一部のネイティブサイズは名目の比率と わずかにずれます（1K の 16:9 は 1424×800）。これはモデル自身の出力サイズです。納品前に比率・サイズ・C2PA クレデンシャルに記載されたモデルを確認し、一致しない場合は納品せず、ジョブは失敗となり課金されません。

- `size` にはピクセルサイズ（例 `2560x1440`）も指定できます。比率の判定だけに使い（9 種類のどれかと 1.5% 以内）、納品は上表のその比率のオリジナルサイズです。グレードは `resolution` で決まり、`resolution` がないときは長辺で判断します：1600 以下は 1K、1601〜3200 は 2K。

- このモデルは 1K と 2K のみです。4K（`resolution: "4K"`、または `size` の長辺が 3200 超）を指定すると、すぐに 400 `unsupported_resolution` を返し、課金されません。2K は `resolution: "2K"` を指定してください。

## 画像から画像と参照画像

- `image`（1 枚）または `images`（複数枚、最大 8 枚。9 枚目以降は使われません）を渡すと画像から画像になります。どう変えるかはプロンプトに書いてください。`POST /v1/images/edits` も同じパラメータで使えます。

- どちらのエンドポイントも JSON の本文だけを受け付け、multipart でのファイルアップロードには対応していません。そのため OpenAI SDK の `images.edit()` はそのままでは使えません。下の例のように、リンクまたは base64 で渡してください。

- 参照画像はそれぞれ、公開されている画像の URL（http または https）、data: URI、またはそのままの base64 で渡せます。1 枚 16MB までで、JPEG、PNG、WebP などの一般的な形式に対応しています。

- URL は画像そのものを直接ダウンロードできるものにしてください。ウェブページや、ログインが必要な URL、直リンク禁止の URL は使えません。読み込めない参照画像は送信時に 400 で拒否され、どの画像がなぜ読めないかが示されます。タスクは作成されず、課金もされません。

- 編集や合成のときも出力の比率は `size` に従い（省略時は 1:1）、参照画像には自動で合わせません。元画像の比率を保つには `size` をその比率にしてください。納品はモデルのオリジナルで、切り抜き・リサイズはしません。何度も編集を重ねるときは、前回の結果を次の参照画像に指定してください。

- 参照画像は当サイトで代わりにホストし、7 日間保存します。

**参照画像 2 枚で画像から画像**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.5", "prompt": "人物はそのままに、背景を夜の海辺に変えて、暖かい色のストリングライトを添える", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## タスクの状態と返却フィールド

`GET /v1/images/jobs/{id}` は次のステータスを返します。各フィールドの説明は [非同期タスク](https://docs.kovapi.com/ja/guide/async-jobs#fields) をご覧ください。2〜3 秒ごとに照会するか、Webhook を使ってください。

| ステータス | 意味 |
| --- | --- |
| queued | 順番待ち。`queue_position`（前にあるタスク数）と `eta_seconds`（予想待ち時間）が付きます。 |
| processing | 生成中。 |
| succeeded | 完了。結果は `data[0].url`、課金の内訳は `usage` にあります。 |
| failed | 失敗。理由は `error` にあり、予約したクレジットは全額返金されます。 |

1 つのアカウントで同時に生成できるタスクは 50 件までで、それ以上は送信順に順番待ちになります。15 分たっても始まらないタスクは失敗となり、全額返金されます。タスクの記録は 3 日間、画像のリンクは 7 日間保存されます。

## 生成にかかる時間

混雑していなければ、送信から結果まで通常 20〜40 秒です。2K や参照画像が多い場合は少し遅くなります。Beta 期間中は混雑時にさらに時間がかかったり失敗したりすることがあります（失敗は課金されません）。

## エラーと返金

送信時のエラーはすぐに HTTP 4xx / 5xx で返り、タスクは作成されず、課金もされません。受け付け後の失敗は照会エンドポイントで報告され、確保額は全額返金されます。すべてのコードは [エラーコード](https://docs.kovapi.com/ja/guide/errors) に載っています。

### 送信時に返るエラー

| HTTP | code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` に `prompt` がありません。 | `prompt` を追加してください。 |
| 400 | invalid_request | 参照画像を読み込めない（リンク切れ、画像ではない、16MB 超など。どれがなぜ読めないかは `message` に記載）、`/v1/images/edits` に参照画像がない、本文が JSON オブジェクトでない、または `n` が整数ではありません。 | `message` の内容に沿って直してから、もう一度送信してください。 |
| 400 | unsupported_resolution | このモデルには選択した解像度のグレードがありません（たとえば Grok の画像生成には 4K がありません）。 | 別のグレードを選んでください。各モデルが対応するグレードは、そのドキュメントに載っています。 |
| 400 | model_not_found | モデル ID のつづりが違う・`model` がない・そのモデルをこのエンドポイントでは使えない（たとえば対話モデルで画像のエンドポイントを呼び出した）のいずれかです。 | `GET /v1/models` または [API リファレンス](https://docs.kovapi.com/ja/api) にあるモデル ID を使ってください。 |
| 401 | invalid_api_key | キーが存在しない・削除された・無効化されているか、アカウントが停止されています。 | コンソールの「API Keys」ページでキーを確認してください。 |
| 402 | insufficient_quota | このリクエストの分を確保するだけの残高がありません。ゲートウェイはまずリクエストにかかりうる最大の費用を確保するため、同時に多くの呼び出しを送ったときにも起こることがあります。 | 一度に多くの呼び出しを送った直後なら、数秒待って再試行してください。そうでなければチャージしてください。 |
| 429 | rate_limit_exceeded | このキーに設定した 1 分あたりのリクエスト数の上限を超えました（直近 60 秒で数えます）。`Retry-After` ヘッダーは付きません。 | 数秒待ってから再試行するか、コンソールでこのキーの上限を引き上げてください。 |
| 503 | model_maintenance | モデルのメンテナンス中で、リクエストを受け付けていません。その間、別のモデルが代わりに回答することもありません。 | メンテナンスが終わってから再試行してください。状況は [サービス状態](https://kovapi.com/ja/status) で確認できます。 |
| 503 | service_unavailable | 当サイト側の一時的なエラーです（参照素材の保存に失敗した場合など）。`/v1/responses` が一時的に処理できないときも、`Retry-After` 付きで 503 を返します。 | しばらくしてから再試行してください。 |

### 失敗したタスク（`status` が `failed`）

| code | 発生する場面 | 対処 |
| --- | --- | --- |
| moderation_blocked | 画像：モデル提供元の安全審査がプロンプトまたは参照画像を拒否しました（コードが `content_policy_violation` の場合もあります）。 | プロンプトを書き直すか、参照画像を差し替えてください。そのまま再送信しても、たいてい再び拒否されます。 |
| upstream_error | その他の失敗：自動で再試行しても失敗した、順番待ちが 15 分を過ぎても始まらなかった、上流が理由を示さずに拒否した、などです。具体的な状況は `message` に書かれています。 | たいていは再送信すれば成功します。 |

## ポーリングの代わりに Webhook を使う

送信時に `callback_url` を付けると、タスクが終わった時点で（成功・失敗とも）、照会エンドポイントが返すものとまったく同じ内容をゲートウェイがその URL へ送ります。署名付きで、届かなかった場合は自動で再試行します。コンソールの「設定 → Webhook」で、アカウント全体の送信先を設定することもできます。 [Webhook のドキュメント →](https://docs.kovapi.com/ja/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.5", "prompt": "夕暮れの路地にあるカフェの入口、黒板にチョークで「本日のおすすめ：金木犀ラテ 480円」、そばに茶トラの猫、写実的な写真", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```