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

# Seedream-5.0-Pro 이미지 생성

> Seedream 5.0 Pro 모델로 1K/2K 해상도의 고품질 이미지를 생성합니다

> [!NOTE]
>
> **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.

* ByteDance Seed 팀이 개발한 Seedream 5.0 Pro 고품질 이미지 생성 모델
* model 파라미터로 `doubao-seedream-5-0-pro` 모델 선택
* 파라미터는 `Seedream-5.0` 과 기본적으로 동일하며, 차이는 Pro 가 **1K** 와 **2K** 해상도를 지원한다는 점입니다
* 텍스트-이미지, 이미지-이미지, 다중 참조 이미지 등 생성 모드를 지원
* **과금 규칙**: 첫 번째 참조 이미지는 무료이고 두 번째 참조 이미지부터 정상 규칙으로 과금됩니다
* 비동기 작업 관리, 작업 ID로 결과 조회

> [!WARNING]
>
> **중요 변경**: 더 나은 성능과 비용 제어를 위해 `image_urls` 에 base64 이미지 데이터를 직접 전달하는 방식을 더 이상 지원하지 않습니다. 먼저 [Upload 이미지 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 로 이미지를 업로드해 URL 을 받은 뒤 이 API 를 호출하세요.

## Authorizations

**Authorization** `string` *required*

모든 API 는 Bearer Token 인증이 필요합니다

API Key 발급: [API Key 관리 페이지](https://toapis.com/console/token) 에서 API Key 를 받으세요

요청 헤더에 추가하세요:

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: doubao-seedream-5-0-pro)

이미지 생성 모델 이름

예: `"doubao-seedream-5-0-pro"`

**prompt** `string` *required*

이미지 생성 텍스트 설명

**size** `string` (default: 1:1)

이미지 화면 비율

`layer_decomposition` 을 활성화하면 이 필드는 해상도 프리셋 `1K` 또는 `2K` 를 직접 전달하는 용도로 바뀝니다.

지원하는 화면 비율:

* `1:1` - 정사각형(기본값)
* `4:3` - 가로 4:3
* `3:4` - 세로 3:4
* `16:9` - 가로 와이드스크린
* `9:16` - 세로 긴 이미지
* `3:2` - 가로 3:2
* `2:3` - 세로 2:3
* `21:9` - 울트라 와이드
* `9:21` - 울트라 톨

**n** `integer` (default: 1)

생성할 이미지 수

범위: 1-10(최소 1장, 최대 10장)

기본값: 1

**주의:**

* 참조 이미지 + 생성 이미지 총수가 15 이하여야 합니다
* **순수 숫자(예: `1`)를 입력하고 따옴표를 붙이지 마세요. 그렇지 않으면 오류가 발생합니다**

생성 수량과 참조 이미지 수량에 따라 선차감되며 첫 번째 참조 이미지는 무료입니다

**layer\_decomposition** `boolean` (default: false)

Seedream 5.0 Pro 전용 레이어 분리 기능을 사용할지 여부입니다.

* `false`: 일반 평면 이미지 반환(기본값)
* `true`: 배경 이미지와 투명 채널을 가진 여러 개의 독립 PNG 레이어 반환

활성화하면 작업 조회 결과의 각 `result.data[]` 항목에 `z_index` 가 추가로 반환되고, 독립 레이어에는 `bounding_box`, `name`, `description` 이 추가로 반환됩니다. 이 파라미터는 Seedream 5.0 Pro 만 지원합니다.

**image\_urls** `string[]`

이미지-이미지 또는 이미지 편집에 사용하는 참조 이미지 URL 목록

**⚠️ URL 형식만 지원(base64 미지원)**

* 공개적으로 접근 가능한 이미지 URL(http\:// 또는 https\://)
* [Upload 이미지 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 로 로컬 이미지를 업로드해 URL 받기

**제한:**

* 이미지 개수: 1-10장
* 이미지 형식: jpeg, png
* 화면 비율(가로/세로) 범위: \[1/3, 3]
* 가로와 세로(px) > 14
* 크기: 10MB 이하
* 총 픽셀: 6000×6000 px 이하

**과금 설명:**

* 첫 번째 참조 이미지 무료
* 두 번째 참조 이미지부터 정상 규칙으로 과금

**metadata** `object`

Seedream 5.0 Pro 모델의 고급 설정을 전달하는 채널 전용 파라미터

**metadata 속성**

**metadata.resolution** `string` (default: 2K)

이미지 해상도

지원하는 해상도:

* `1K` - 기본 해상도
* `2K` - 표준 해상도(기본값)

> **주의:** Seedream 5.0 Pro 는 3K 와 4K 해상도를 지원하지 않습니다. Pro 가 아닌 Seedream 5.0 은 2K 와 3K 를 지원합니다

**metadata.sequential\_image\_generation** `string` (default: disabled)

순차 이미지 생성 모드(더우바오 전용 기능)

여러 이미지를 생성할지 제어합니다:

* `disabled`: 순차 모드 비활성화, 참조 이미지가 여러 장이어도 1장만 생성(기본값)
* `auto`: 순차 모드 활성화, 여러 이미지 생성 가능

**사용 안내:**

* ✅ `n: 3` 설정 또는 `sequential_image_generation: "auto"` + `max_images: 3` 사용
* ✅ 텍스트-이미지 세트 지원: 텍스트 프롬프트만 제공해 최대 10장 생성
* ✅ 이미지-이미지/이미지-세트 지원: `image_urls` 를 제공해 참조 이미지 기반으로 여러 이미지 생성
* ⚠️ `n > 1` 이면 자동으로 `auto` 로 설정됩니다

**주의:**

* 입력 참조 이미지 수 + 최종 생성 이미지 수 ≤ 15장

**metadata.sequential\_image\_generation\_options** `object`

순차 이미지 생성 옵션

`sequential_image_generation` 을 `auto` 로 설정한 경우 사용할 수 있습니다

**속성:**

* `max_images`(정수): 생성할 이미지 수 지정, 범위 1-10

**예시:**

```json theme={null}
"sequential_image_generation_options": { "max_images": 3 }
```

**metadata.watermark** `boolean` (default: false)

생성 이미지에 워터마크를 추가할지 여부

* `true`: 워터마크 추가
* `false`: 워터마크 없음(기본값)

## 응답

**id** `string`

상태 조회에 사용하는 작업 고유 식별자

**object** `string`

객체 유형, 항상 `generation.task`

**model** `string`

사용한 모델 이름

**status** `string`

작업 상태

* `queued` - 처리 대기 중
* `in_progress` - 처리 중
* `completed` - 성공적으로 완료
* `failed` - 실패

**progress** `integer`

작업 진행률(0-100)

**created\_at** `integer`

작업 생성 타임스탬프(Unix 타임스탬프)

**metadata** `object`

작업 메타데이터

**completed\_at** `integer`

작업 완료 타임스탬프(Unix 타임스탬프). 작업이 완료된 뒤에만 반환됩니다.

**expires\_at** `integer`

결과 파일 만료 타임스탬프(Unix 타임스탬프). 만료 전에 결과 파일을 다운로드하거나 다른 곳에 저장하세요.

**result** `object`

작업 성공 후의 생성 결과. `status` 가 `completed` 일 때만 반환됩니다.

**result.type** `string`

결과 유형, 이미지 작업은 항상 `image` 입니다.

**result.data** `array`

이미지 결과 목록. 레이어 분리를 활성화하면 첫 번째 요소가 보통 배경 이미지이고 나머지 요소가 투명 채널을 가진 독립 PNG 레이어입니다.

**result.data\[].url** `string`

배경 이미지 또는 독립 레이어의 공개 접근 주소입니다.

**result.data\[].z\_index** `integer`

레이어 적층 순서. `layer_decomposition` 을 활성화하면 배경 이미지가 보통 `0` 이고 독립 레이어가 순서대로 증가합니다.

**result.data\[].size** `string`

현재 배경 이미지 또는 독립 레이어의 픽셀 크기입니다. 예: `2048x2048`.

**result.data\[].output\_format** `string`

현재 결과 항목의 파일 형식입니다. 배경 이미지는 요청한 형식일 수 있고 투명 독립 레이어는 `png` 입니다.

**result.data\[].bounding\_box** `object`

배경 이미지에서 독립 레이어의 위치이며 `absolute` 절대 좌표와 `normalized` 정규화 좌표를 포함합니다.

**result.data\[].bounding\_box.absolute** `array`

배경 이미지에서 레이어의 절대 픽셀 좌표로 `[x1, y1, x2, y2]` 형식이며 각각 좌측 상단과 우측 하단 좌표를 나타냅니다.

**result.data\[].bounding\_box.normalized** `array`

레이어의 정규화 좌표로 `[x1, y1, x2, y2]` 형식이며 좌표 범위는 `0-1000` 입니다.

**result.data\[].name** `string`

레이어 이름입니다.

**result.data\[].description** `string`

레이어 내용 설명입니다.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A cute panda playing in a bamboo forest",
    "size": "1:1",
    "n": 1,
    "metadata": {
      "resolution": "2K"
    }
  }'
```

```bash cURL (이미지-이미지) theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A cute panda playing in a bamboo forest",
    "size": "1:1",
    "n": 1,
    "image_urls": [
      "https://example.com/panda.jpg"
    ],
    "metadata": {
      "resolution": "1K"
    }
  }'
```

```bash cURL (레이어 분리) theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "Precisely separate the image into a base image and independent transparent PNG layers.",
    "image_urls": [
      "https://example.com/office-desk.png"
    ],
    "size": "2K",
    "n": 1,
    "layer_decomposition": true
  }'
```

> [!NOTE]
>
> `layer_decomposition` 을 활성화할 때는 `size` 에 `1K` 또는 `2K` 해상도 프리셋을 직접 사용하고 `WIDTHxHEIGHT` 명시적 픽셀 크기는 사용하지 마세요. 제출에 성공하면 `GET /v1/images/generations/{task_id}` 로 전체 레이어 결과를 조회하세요.

```bash cURL (일괄 생성) theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A cute panda playing in a bamboo forest",
    "size": "1:1",
    "n": 4,
    "metadata": {
      "resolution": "2K",
      "sequential_image_generation": "auto",
      "sequential_image_generation_options": { "max_images": 4 },
      "watermark": false
    }
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "doubao-seedream-5-0-pro",
        "prompt": "A cute panda playing in a bamboo forest",
        "size": "1:1",
        "n": 1,
        "metadata": {
            "resolution": "2K"
        }
    }
)

task = response.json()
print(f"任务 ID: {task['id']}")
print(f"Status: {task['status']}")
```

```python Python (이미지-이미지) theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "doubao-seedream-5-0-pro",
        "prompt": "A cute panda playing in a bamboo forest",
        "size": "1:1",
        "n": 1,
        "image_urls": ["https://example.com/panda.jpg"],
        "metadata": {
            "resolution": "1K"
        }
    }
)

task = response.json()
print(f"任务 ID: {task['id']}")
print(f"Status: {task['status']}")
```

```javascript JavaScript theme={null}
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'doubao-seedream-5-0-pro',
    prompt: 'A cute panda playing in a bamboo forest',
    size: '1:1',
    n: 1,
    metadata: {
      resolution: '2K'
    }
  })
});

const task = await response.json();
console.log(`任务 ID: ${task.id}`);
console.log(`Status: ${task.status}`);
```

```javascript JavaScript (이미지-이미지) theme={null}
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'doubao-seedream-5-0-pro',
    prompt: 'A cute panda playing in a bamboo forest',
    size: '1:1',
    n: 1,
    image_urls: ['https://example.com/panda.jpg'],
    metadata: {
      resolution: '1K'
    }
  })
});

const task = await response.json();
console.log(`任务 ID: ${task.id}`);
console.log(`Status: ${task.status}`);
```

```json 200 theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "doubao-seedream-5-0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}
```

```json 200 레이어 분리 완료 theme={null}
{
  "completed_at": 1787128810,
  "created_at": 1787128650,
  "expires_at": 1787215210,
  "id": "tsk_img_example_layer_decomposition",
  "model": "doubao-seedream-5-0-pro",
  "object": "generation.task",
  "progress": 100,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/images/example/base.jpg",
        "size": "1600x2848",
        "output_format": "jpeg",
        "z_index": 0
      },
      {
        "url": "https://files.toapis.com/images/example/layer-1.png",
        "size": "3040x955",
        "output_format": "png",
        "z_index": 1,
        "bounding_box": {
          "absolute": [0, 0, 1600, 503],
          "normalized": [0, 0, 999, 176]
        },
        "name": "Background office equipment",
        "description": "The monitor edge and file organizer extracted from the background"
      },
      {
        "url": "https://files.toapis.com/images/example/layer-2.png",
        "size": "1982x1162",
        "output_format": "png",
        "z_index": 2,
        "bounding_box": {
          "absolute": [800, 589, 1599, 1058],
          "normalized": [500, 207, 999, 371]
        },
        "name": "Stacked white papers",
        "description": "Several stacked white office papers extracted from the desk"
      }
    ]
  },
  "status": "completed"
}
```


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