> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream 5.0 Pro · 이미지-이미지

> Seedream 5.0 Pro 이미지-이미지 매개변수, 제한 및 복사 가능한 예제

## 소개

참조 이미지와 편집 지시문으로 단일 이미지 편집, 다중 이미지 융합, 대화형 편집, 투명 이미지 또는 레이어 분해를 수행합니다. 일반 편집은 이미지 1장을, 분해는 기본 이미지와 여러 레이어를 반환합니다.

## 엔드포인트 및 인증

```http theme={null}
POST https://api.gravitex.ai/v1/images/generations
```

`Authorization: Bearer sk-xxxxxxxxxx`와 `Content-Type: application/json`을 사용하세요. 이미지 편집은 같은 JSON 본문으로 `/v1/images/edits`도 사용할 수 있습니다. [매개변수 및 요금](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#인증)

## 요청 매개변수

| 매개변수 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 예 | `dola-seedream-5-0-pro-260628` |
| `prompt` | string | 편집: 필수, 분해: 선택 | 생성 또는 편집 지시문. 레이어 분해 시 분리할 요소를 지정합니다 |
| `image` | string / string\[] | 예 | 참조 URL 또는 Base64. 일반 편집은 최대 10장, 분해는 정확히 1장입니다 |
| `size` | string | 아니요 | 기본값 `2K`. `1K`, `1.5K`, `2K` 또는 사용자 지정 `WIDTHxHEIGHT`; 분해 기본값은 `auto` |
| `output_format` | string | 아니요 | 기본값: `jpeg`. `jpeg` / `png`. 분해 시 기본 이미지에만 적용되며 레이어는 항상 PNG입니다. |
| `response_format` | string | 아니요 | 기본값: `url`. `url`(24시간 유효) 또는 `b64_json` |
| `watermark` | boolean | 아니요 | 기본값: `true`. 오른쪽 아래에 AI 생성 워터마크를 추가합니다 |
| `background` | string | 아니요 | 기본값: `opaque`. `opaque` / `transparent` |
| `optimize_prompt_options` | object | 아니요 | 기본값: `{"mode":"standard"}`. `mode`: `standard`(높은 품질, 느림) 또는 `fast`(빠름, 품질 다소 낮음) |
| `layer_decomposition` | boolean | 아니요 | 기본값: `false`. [레이어 분해 활성화](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0/edits.md#layer_decomposition) |

일반 생성에서 `n`은 생략하거나 `1`을 사용하고, 결과가 여러 장 필요하면 요청을 각각 보내세요. [공통 매개변수](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#요청-매개변수)에서 전체 기본값과 `safety_identifier`를 확인하세요. 두 모델 모두 `quality`, 연속 이미지 생성, 스트리밍 및 웹 검색을 지원하지 않습니다.

### prompt

편집 시 필수입니다. 참조 이미지를 어떻게 사용하거나 변경할지 설명하세요. 분해 시에는 선택 사항이며 분리할 요소를 지정하거나 생략하여 모델이 주요 요소를 자동 인식하게 할 수 있습니다. 중국어는 300자, 영어는 600단어 이내를 권장하며 너무 길면 세부 사항이 누락될 수 있습니다.

대화형 편집에서는 왼쪽 위를 원점으로 하는 정규화 좌표 `[0, 1000]`과 `<bbox>x1 y1 x2 y2</bbox>`로 영역을 지정하세요. 참조 이미지에 상자, 화살표 또는 스케치를 그린 뒤 변경 사항을 설명할 수도 있습니다.

### image

문자열 1개 또는 문자열 배열을 받습니다. 각 항목은 서버에서 접근할 수 있는 공개 URL 또는 `data:image/<format>;base64,<data>` 형식의 Base64 데이터 URI입니다. 형식 이름은 소문자를 사용하세요(예: `data:image/png;base64,iVBORw0...`).

| 제한 | 일반 편집 | 레이어 분해 |
| - | - | - |
| 수량 | 필수, 최대 10장 | 필수, 정확히 1장 |
| 형식 | jpeg, png, webp, bmp, tiff, gif, heic, heif | png, jpeg |
| 가로/세로 비율 | \[1/16, 16] | \[1/16, 16] |
| 가로 및 세로 | 모두 14px 초과 | 총 픽셀 및 비율 제한 적용 |
| 이미지당 용량 | ≤ 30 MB | ≤ 30 MB |
| 총 픽셀 | \[196, 6000×6000] | \[512×512, 6000×6000] |

> [!NOTE]
>
> 총 픽셀 수는 가로 × 세로의 곱이며 각 변의 최솟값을 뜻하지 않습니다. 투명 이미지 조건은 아래에 별도로 설명합니다.

### size

[전체 크기 규칙과 해상도 표](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#size)

분해는 `1K`, `1.5K`, `2K`, `auto`(기본값)만 지원하며 사용자 지정 픽셀 크기는 지원하지 않습니다.

### background

| 값 | 설명 |
| - | - |
| `opaque` | 알파 채널 없는 RGB 출력 (기본값) |
| `transparent` | 알파 채널이 있는 RGBA 출력. PNG를 사용하세요 |

> [!WARNING]
>
> 5.0 Pro는 텍스트만으로 투명 이미지를 생성할 수 없습니다. 투명 이미지 편집에는 알파 채널이 있는 참조 이미지가 정확히 1장 필요합니다.

> [!WARNING]
>
> `background: "transparent"`와 JPEG 출력을 함께 사용하지 마세요. 레이어 분해 모드에서는 `background`를 전달하지 마세요.

### layer\_decomposition

`layer_decomposition: true`로 이미지 1장을 기본 이미지 1장과 알파 채널을 가진 독립 PNG 레이어 최대 16개로 분해합니다. 기본값은 `false`입니다.

* `image`는 필수이며 입력은 정확히 1장이어야 합니다.
* 레이어 하나라도 실패하면 전체 요청이 실패하며 부분 성공은 지원하지 않습니다.
* 요청한 레이어가 상한을 넘으면 일부 정보가 누락될 수 있습니다.
* 응답에는 `z_index`, `name`, `description`, `bounding_box`가 포함됩니다.
* 기본 이미지와 모든 레이어는 `usage.generated_images`에 포함됩니다.

## 호출 예제

각 예제는 전체 JSON 본문과 동일한 cURL을 제공합니다. `sk-xxxxxxxxxx`를 자신의 API 키로 바꾸세요. 입력 URL은 로그인 없이 접근할 수 있는 공개 주소입니다. 응답 URL은 구조 예시입니다.

### 단일 이미지 편집

```json 요청 본문 theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "참조 이미지 속 강아지의 외형을 유지하면서 수채화 일러스트로 표현하세요",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "참조 이미지 속 강아지의 외형을 유지하면서 수채화 일러스트로 표현하세요",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "size": "2K"
  }'
```

### 다중 이미지 융합

```json 요청 본문 theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "이미지 1의 강아지를 이미지 2의 호숫가 장면에 배치하고, 강아지의 외형을 유지하면서 조명과 원근을 맞추세요",
  "image": [
    "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
  ],
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "이미지 1의 강아지를 이미지 2의 호숫가 장면에 배치하고, 강아지의 외형을 유지하면서 조명과 원근을 맞추세요",
    "image": [
      "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
      "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
    ],
    "size": "2K"
  }'
```

### 대화형 편집

```json 요청 본문 theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "<bbox>0 0 1000 300</bbox> 영역의 배경만 연한 파란색으로 바꾸고 강아지와 나머지 영역은 그대로 유지하세요",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "size": "2K",
  "output_format": "png"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "<bbox>0 0 1000 300</bbox> 영역의 배경만 연한 파란색으로 바꾸고 강아지와 나머지 영역은 그대로 유지하세요",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "size": "2K",
    "output_format": "png"
  }'
```

### 투명 이미지 편집

```json 요청 본문 theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "참조 이미지의 색상 도형을 금속 질감으로 바꾸고 투명 배경은 유지하세요",
  "image": "https://raw.githubusercontent.com/pnggroup/libpng/libpng16/pngtest.png",
  "background": "transparent",
  "output_format": "png"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "참조 이미지의 색상 도형을 금속 질감으로 바꾸고 투명 배경은 유지하세요",
    "image": "https://raw.githubusercontent.com/pnggroup/libpng/libpng16/pngtest.png",
    "background": "transparent",
    "output_format": "png"
  }'
```

### 레이어 분해

```json 요청 본문 theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "참조 이미지의 하늘, 산, 호수, 전경을 각각 독립 레이어로 분해하세요",
  "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
  "layer_decomposition": true,
  "size": "2K",
  "output_format": "jpeg"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "참조 이미지의 하늘, 산, 호수, 전경을 각각 독립 레이어로 분해하세요",
    "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
    "layer_decomposition": true,
    "size": "2K",
    "output_format": "jpeg"
  }'
```

## 성공 응답

일반 편집은 공통 응답 형식을 사용하며 `usage.input_images`는 실제 참조 이미지 수입니다. 아래는 기본 이미지와 레이어 1개만 발췌한 예시이며 `usage`는 전체 결과 기준입니다. 따라서 `generated_images`는 표시된 항목 수보다 큽니다. URL은 구조 예시입니다. [공통 응답](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#성공-응답)

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "created": 1784696685,
  "data": [
    {
      "url": "https://example.com/base.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/layer-1.png",
      "size": "1273x265",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [383, 120, 1655, 384],
        "normalized": [187, 59, 808, 188]
      },
      "name": "Seedream 제목 텍스트",
      "description": "노란색 대형 세리프체의 Seedream 제목 텍스트"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 8,
    "output_tokens": 23107,
    "total_tokens": 23107
  }
}
```

### 응답 필드

[공통 응답 필드](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#응답-필드)

| 추가 필드 | 유형 | 설명 |
| - | - | - |
| `data[].z_index` | integer | 쌓임 순서. 기본 이미지는 0, 레이어는 1부터 시작하며 큰 값일수록 위에 표시 |
| `data[].name` | string | 모델이 생성한 레이어 이름 |
| `data[].description` | string | 레이어 상세 설명 |
| `data[].bounding_box.absolute` | integer\[4] | 출력 기본 이미지에서 레이어의 픽셀 좌표 `[left, top, right, bottom]`. 기본 이미지에는 없음 |
| `data[].bounding_box.normalized` | integer\[4] | 같은 좌표를 `[0, 1000]`으로 정규화한 값. 기본 이미지에는 없음 |

> [!NOTE]
>
> **레이어 복원**: 절대 좌표를 사용하여 레이어를 `(right - left) × (bottom - top)` 크기로 조정한 뒤 기본 이미지의 `(left, top)` 위치에 놓으세요. 정규화 좌표를 `W × H` 캔버스에 적용하면 왼쪽 위 위치는 `(left / 1000 × W, top / 1000 × H)`입니다. `z_index`가 작은 순서부터 쌓으세요.

> [!WARNING]
>
> 결과 URL은 24시간 후 만료되므로 즉시 다운로드하여 저장하세요.

## 요금 및 오류 처리

참조 이미지와 출력 이미지는 별도로 과금되며 기본 이미지와 각 레이어는 개별 출력으로 계산합니다.

[요금](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#요금) · [오류 처리](https://docs.gravitex.ai/ko/api-reference/endpoint/seedream-5.0.md#오류-처리)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.