# Seedream 5.5 API (https://wanapi.app/ko/docs/seedream-5-5)





Seedream 5.5는 텍스트 또는 최대 10개의 참조 이미지로 이미지 한 개를 생성합니다. 레이어 분리는 이미지 하나를 받아 기본 이미지와 투명 레이어를 반환하며, 선택적으로 인쇄 텍스트 인식 결과도 제공합니다.

[Playground 사용해 보기](/ko/models/seedream-5-5#playground) · [OpenAPI JSON](/models/seedream-5-5/openapi.json) · [통합 튜토리얼](/ko/blog/seedream-5-5-api-guide)

## 인증 및 엔드포인트 [#인증-및-엔드포인트]

Wan API 키를 Bearer 토큰으로 사용합니다. 키 하나로 사용 가능한 모든 모델과 그룹에 접근하며, 키에서 그룹을 선택하지 않습니다.

| 메서드  | URL                                                       | 용도            |
| ---- | --------------------------------------------------------- | ------------- |
| POST | `https://api.wanapi.app/seedream55/v1/images/generations` | 이미지 작업 한 개 제출 |
| GET  | `https://api.wanapi.app/seedream55/v1/tasks/{id}`         | 해당 작업 조회      |

모델 ID는 \*\*`seedream-5-5`\*\*입니다. 비동기 엔드포인트이므로 한 번 제출하고 작업 ID를 저장한 뒤 `completed` 또는 `failed`가 될 때까지 폴링합니다. 네트워크 응답이 불확실하다고 다시 제출해서는 안 됩니다.

## 이미지 생성 [#이미지-생성]

```bash
curl https://api.wanapi.app/seedream55/v1/images/generations \
  -H "Authorization: Bearer $WAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning light. No text.",
    "size": "1K"
  }'
```

수락된 요청은 이미지 바이트 대신 작업을 반환합니다.

```json
{"id":"task_example","model":"seedream-5-5","status":"processing","created_at":1794432000}
```

```bash
curl https://api.wanapi.app/seedream55/v1/tasks/task_example \
  -H "Authorization: Bearer $WAN_API_KEY"
```

몇 초 간격으로 같은 ID를 폴링합니다. 애플리케이션이 대기를 중단해도 나중에 재개할 수 있도록 ID를 보관합니다. 이 가이드의 작업 ID와 타임스탬프는 설명용 예시입니다.

## 매개변수 [#매개변수]

| 매개변수                                           | 유형            | 기본값               | 규칙                                                                                 |
| ---------------------------------------------- | ------------- | ----------------- | ---------------------------------------------------------------------------------- |
| `model`                                        | string        | 필수                | `seedream-5-5`                                                                     |
| `prompt`                                       | string        | 생성 시 필수           | 레이어 분리에서는 선택 사항입니다.                                                                |
| `image`                                        | URL 또는 URL 배열 | 없음                | 참조 최대 10개, 레이어에는 정확히 한 개입니다. 모든 참조가 과금됩니다.                                         |
| `size`                                         | string        | `2K`, 레이어는 `auto` | 아래 크기 규칙을 참조합니다.                                                                   |
| `output_format`                                | string        | `png`             | `png` 또는 `jpeg`입니다. 레이어에서는 기본 이미지만 제어합니다.                                          |
| `background`                                   | string        | `auto`            | `auto`, `opaque`, `transparent`입니다. 투명 배경에는 PNG가 필요합니다. 레이어 모드에서는 이 필드를 완전히 생략합니다. |
| `layer_decomposition`                          | boolean       | `false`           | 참조 하나를 기본 이미지와 투명 PNG 레이어로 분리합니다.                                                  |
| `layer_decomposition_options.max_images`       | integer       | `30`              | 기본 이미지를 포함한 총 이미지 제한 2–100입니다. 레이어 모드 전용입니다.                                       |
| `layer_decomposition_options.text_recognition` | boolean       | `false`           | 레이어의 인쇄 텍스트 메타데이터를 요청합니다. 레이어 모드 전용입니다.                                            |
| `optimize_prompt_options.mode`                 | string        | `standard`        | `standard` 모드만 지원합니다.                                                              |
| `watermark`                                    | boolean       | `false`           | AI 생성 워터마크를 요청합니다.                                                                 |
| `content_filter`                               | boolean       | `true`            | 고객 API는 false를 허용합니다. Playground에서는 관리자만 비활성화할 수 있습니다.                             |

`n`, `seed`, `stream`, `resolution`, `aspect_ratio`, `image_urls`, `response_format` 매개변수는 지원하지 않습니다. 문서에 없는 필드는 버려지며 해당 기능을 활성화하지 않습니다. Multipart 업로드, Base64 및 data URI는 거부됩니다.

## 출력 크기 [#출력-크기]

생성은 `1K`, `1.5K`, `2K` 또는 정확한 `WIDTHxHEIGHT` 픽셀을 지원합니다. 정확한 크기는 총 **921,600–4,624,220픽셀**, 화면 비율 **1:16–16:1**이어야 합니다. 예를 들어 `2048x1152`는 유효합니다. `16:9` 같은 비율은 크기 값이 아닙니다.

레이어 분리는 `auto`, `1K`, `1.5K`, `2K`를 지원하며 정확한 픽셀 치수는 지원하지 않습니다. `auto`는 입력을 따르며 높은 출력 요율로 금액을 사전 확보합니다. 3K·4K 프리셋은 없습니다.

<span id="reference-images-and-editing" />

## 참조 이미지 및 편집 [#참조-이미지-및-편집]

직접 호스팅한 공개 HTTP(S) URL을 제공하며 인증 정보를 포함하지 않습니다. 지원 형식은 JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC 및 HEIF이며, 이미지당 최대 30 MB, 총 최대 36,000,000픽셀입니다. AVIF와 JP2는 지원하지 않습니다. URL은 로그인이나 브라우저 확인 절차 없이 이미지를 직접 제공해야 합니다.

```json
{
  "model": "seedream-5-5",
  "prompt": "Change the scene to a snowy winter night. Keep the lighthouse and its composition.",
  "image": "https://your-cdn.example/lighthouse.jpg",
  "size": "2K"
}
```

여러 참조에는 URL 배열을 전달하고 프롬프트에서 각 이미지의 역할을 설명합니다. 결과는 여전히 이미지 한 개입니다. 예시 참조 URL은 자리표시자이므로 직접 접근 가능한 파일로 바꿉니다.

## 레이어 분리 및 텍스트 인식 [#레이어-분리-및-텍스트-인식]

```json
{
  "model": "seedream-5-5",
  "image": "https://your-cdn.example/poster.png",
  "size": "1K",
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 4,
    "text_recognition": true
  }
}
```

제한에는 기본 이미지가 포함됩니다. `4`는 기본 이미지에 레이어 네 개를 더한다는 뜻이 아니라 최대 네 개의 반환 이미지를 뜻합니다. 실제 반환 수는 더 적을 수 있습니다. 자동 분리에는 `prompt`를 생략하거나 분리할 요소를 명시합니다. 프롬프트에서 제외한 텍스트는 결과에서도 제외될 수 있습니다.

레이어는 투명 PNG 파일입니다. 기본 이미지를 0으로 두고 `z_index` 오름차순으로 이미지를 재구성합니다. 경계 상자가 제공되면 레이어를 해당 상자 크기로 조정한 뒤 배치합니다. 레이어 파일의 픽셀 치수는 배치 치수와 다를 수 있습니다.

선택 사항인 `text_recognition`에는 전체 `text`와 `lines`가 포함됩니다. 각 줄에는 `bounding_box`와 스타일이 적용된 `runs`가 포함될 수 있습니다. run의 `style`에는 `similar_font_family`, `foreground_color` (`#RRGGBB`), `bold`, `italic`, `underline`, `strikethrough`, `shadow` 및 `translucent`가 포함될 수 있습니다. 이는 모델의 추정치입니다. 장식 글자나 손글씨에는 텍스트 결과가 없을 수 있으므로 이 필드를 선택 사항으로 취급합니다.

## 완료 응답 [#완료-응답]

```json
{
  "id": "task_example",
  "model": "seedream-5-5",
  "status": "completed",
  "created_at": 1794432000,
  "output": {
    "data": [
      {
        "url": "https://api.wanapi.app/v1/tasks/task_example/artifacts/image-1/content?access=EXAMPLE",
        "size": "1248x832",
        "output_format": "png"
      }
    ]
  }
}
```

각 이미지에는 `url`과 `size`가 있습니다. 다른 필드로 `output_format`, `background`, `z_index`, `name`, `description`, `bounding_box` 및 `text_recognition`이 포함될 수 있습니다. `bounding_box.absolute`는 기본 이미지 픽셀 단위의 `[left, top, right, bottom]`입니다. `bounding_box.normalized`는 같은 좌표를 0–1000으로 환산합니다. 모든 이미지에 선택적 메타데이터가 있다고 가정하지 않습니다.

이미지 URL은 비공개 다운로드 링크로 취급하고 필요한 파일을 저장합니다. `access` 토큰이 있는 URL은 계정 API 키를 노출하지 않고 열 수 있습니다.

## 요금 [#요금]

<Seedream55ModelPricing />

출력 픽셀 경계는 **2,610,000픽셀**입니다. 요금은 다음과 같이 계산합니다.

```text
lower-band output count × lower-band rate
+ higher-band output count × higher-band rate
+ reference image count × reference rate
```

첫 번째 참조와 레이어 원본을 포함한 모든 참조가 과금됩니다. 생성과 레이어의 출력 요율은 같습니다. 제출 시 출력 한 개 또는 레이어 `max_images` 제한과 참조에 해당하는 금액을 사전 확보합니다. 완료 시 반환된 각 이미지의 실제 픽셀 치수로 정산하고 사용하지 않은 사전 확보 금액을 해제합니다. 실행 중 요율이 변경되어도 수락된 작업의 가격 스냅샷은 유지됩니다. 실패한 작업은 환불됩니다.

## 오류 및 재시도 동작 [#오류-및-재시도-동작]

유효하지 않은 매개변수는 제출 전에 거부됩니다. 잔액이나 키 할당량이 부족하면 생성할 수 없습니다. 제출과 폴링 모두 인증 및 소유권 확인을 거칩니다. 실패한 작업은 `error` 객체와 함께 `status: "failed"`를 반환합니다.

상태 조회에 실패하면 같은 작업 ID로 재시도합니다. 시간 초과 후에도 **생성 POST를 자동 반복하지 마세요**. 이미 수락되었을 수 있습니다. 상위 서비스가 정상 진행 상태를 보고하는 동안 작업은 대기 상태로 유지됩니다. 연속 3시간 동안 정상 상위 상태나 성공적인 전달이 없으면 작업이 실패하고 환불됩니다.

작업 ID를 저장하고 재개하는 애플리케이션 루프는 [Seedream 5.5 튜토리얼](/ko/blog/seedream-5-5-api-guide)을 참조합니다.
