# Seedream 5.5 — /images/generations

Seedream 5.5(Beta) 이미지 생성 API입니다. ByteDance 최신 세대 Seedream 이미지 모델로 텍스트-투-이미지, 편집, 여러 이미지 합성을 한 모델로 처리하며 비동기 작업으로 동작합니다. 제출하면 작업 ID가 바로 돌아오고(HTTP 202), 이후 결과를 조회하거나 웹훅으로 받습니다. 1K와 2K, 9가지 비율이며 PNG 원본을 전달합니다. 장당 과금되고 실패하면 과금되지 않습니다. Beta 기간에는 혼잡할 때 실패하거나 느려질 수 있으니 그대로 다시 제출하세요.

**엔드포인트:** `POST https://kovapi.com/v1/images/generations`

## 빠른 시작

세 단계면 됩니다: 작업 제출 → 결과 조회 → 이미지 링크 받기. 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": "해 질 녘 골목의 카페 입구, 칠판에 분필로 쓴 “오늘의 메뉴: 계화 라테 4,800원”, 옆에 엎드린 치즈 고양이, 사실적인 사진", "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": "해 질 녘 골목의 카페 입구, 칠판에 분필로 쓴 “오늘의 메뉴: 계화 라테 4,800원”, 옆에 엎드린 치즈 고양이, 사실적인 사진",
    "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 | 아니오 | 참조 이미지. 넣으면 편집·합성이 됩니다. 한 장은 `image`, 여러 장은 `images`(최대 10장). 공개 이미지 URL, data: URI, base64를 쓸 수 있습니다. 여러 장이면 순서대로 각 이미지의 용도를 프롬프트에 적어 주세요(예: "이미지 1의 인물이 이미지 2의 카페에 앉아 있다"). |
| n | integer | 아니오 | 항상 1: 요청당 1장입니다. 여러 장이 필요하면 작업을 여러 개 동시에 제출하세요. 다른 값은 제출 시 400을 반환하고 과금되지 않습니다. |
| callback_url | string | 아니오 | 작업이 끝나면 결과를 보낼 주소. 아래 웹훅 부분을 보세요. |

그 밖의 OpenAI 매개변수(`quality`, `background`, `output_format`, `style` 등)는 지원하지 않습니다. 넣어도 효과가 없고 가격도 바뀌지 않습니다. 결과는 항상 PNG 원본이며 `url`로 반환됩니다. `response_format: "b64_json"`이면 결과에 base64도 함께 담깁니다.

## 가격

장당 과금이며 가격은 등급으로만 정해집니다. 비율이나 텍스트-투-이미지 / 이미지-투-이미지 여부와는 관계없습니다. 제출할 때 등급 가격만큼 예약되고, 작업이 실패하면 전액 환불됩니다. 1크레딧 = $0.005.

| 등급 | 장당 크레딧 | 장당 가격(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`(한 장) 또는 `images`(여러 장, 최대 8장이며 8장을 넘는 것은 쓰지 않음)를 보내면 이미지-투-이미지로 실행됩니다. 무엇을 어떻게 바꿀지는 프롬프트에 적으세요. `POST /v1/images/edits`도 같은 파라미터를 받습니다.

- 두 엔드포인트 모두 JSON 본문만 받고 multipart 파일 업로드는 받지 않습니다. 그래서 OpenAI SDK의 `images.edit()`은 그대로 쓸 수 없으니, 아래 예시처럼 링크나 base64를 보내세요.

- 참조 이미지는 각각 공개 이미지 URL(http 또는 https), data: URI, 순수 base64 중 하나로 보낼 수 있습니다. 한 장당 16MB 이하이며, JPEG, PNG, WebP 같은 일반적인 형식이면 됩니다.

- 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/ko/guide/async-jobs#fields)에 있습니다. 2~3초마다 조회하거나 웹훅을 쓰세요.

| 상태 | 의미 |
| --- | --- |
| queued | 대기 중. `queue_position`(앞에 있는 작업 수)과 `eta_seconds`(예상 대기 시간)가 함께 옵니다. |
| processing | 생성 중. |
| succeeded | 완료. 결과는 `data[0].url`, 과금 내역은 `usage`에 있습니다. |
| failed | 실패. 사유는 `error`에 있고, 예약된 크레딧은 전액 환불됩니다. |

한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 이미지 링크는 7일 동안 보관됩니다.

## 생성 시간

혼잡하지 않으면 제출부터 결과까지 보통 20~40초입니다. 2K나 참조 이미지가 많으면 조금 느립니다. Beta 기간에는 혼잡할 때 더 오래 걸리거나 실패할 수 있습니다(실패는 과금되지 않음).

## 오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 [오류 코드](https://docs.kovapi.com/ko/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/ko/api)에 있는 모델 ID를 쓰세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 [서비스 상태](https://kovapi.com/ko/status)에서 볼 수 있습니다. |
| 503 | service_unavailable | 참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. `/v1/responses`는 잠시 요청을 처리할 수 없을 때도 `Retry-After`와 함께 503을 돌려줍니다. | 잠시 후 다시 시도하세요. |

### 작업 실패(`status`가 `failed`)

| code | 언제 나오나요 | 조치 |
| --- | --- | --- |
| moderation_blocked | 이미지: 모델 제공사의 안전 시스템이 프롬프트나 참조 이미지를 거부했습니다(코드가 `content_policy_violation`일 수도 있습니다). | 프롬프트를 고쳐 쓰거나 참조 이미지를 바꾸세요. 그대로 다시 제출하면 대개 다시 거부됩니다. |
| upstream_error | 그 밖의 실패: 자동 재시도 후에도 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 `message`에 있습니다. | 다시 제출하면 대개 성공합니다. |

## 조회 대신 웹훅으로 받기

제출할 때 `callback_url`을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. [웹훅 문서 →](https://docs.kovapi.com/ko/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": "해 질 녘 골목의 카페 입구, 칠판에 분필로 쓴 “오늘의 메뉴: 계화 라테 4,800원”, 옆에 엎드린 치즈 고양이, 사실적인 사진", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```