> ## 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` 로 바꿔 주세요.
</Note>

* 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](../../uploads/images) 로 이미지를 업로드해 URL 을 받은 뒤 이 API 를 호출하세요.
</Warning>

## Authorizations

<ParamField header="Authorization" type="string" required>
  모든 API 는 Bearer Token 인증이 필요합니다

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

  요청 헤더에 추가하세요:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" default="doubao-seedream-5-0-pro" required>
  이미지 생성 모델 이름

  예: `"doubao-seedream-5-0-pro"`
</ParamField>

<ParamField body="prompt" type="string" required>
  이미지 생성 텍스트 설명
</ParamField>

<ParamField body="size" type="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` - 울트라 톨
</ParamField>

<ParamField body="n" type="integer" default={1}>
  생성할 이미지 수

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

  기본값: 1

  **주의:**

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

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

<ParamField body="layer_decomposition" type="boolean" default={false}>
  Seedream 5.0 Pro 전용 레이어 분리 기능을 사용할지 여부입니다.

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

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

<ParamField body="image_urls" type="string[]">
  이미지-이미지 또는 이미지 편집에 사용하는 참조 이미지 URL 목록

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

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

  **제한:**

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

  **과금 설명:**

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

<ParamField body="metadata" type="object">
  Seedream 5.0 Pro 모델의 고급 설정을 전달하는 채널 전용 파라미터

  <Expandable title="metadata 속성">
    <ParamField body="metadata.resolution" type="string" default="2K">
      이미지 해상도

      지원하는 해상도:

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

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

    <ParamField body="metadata.sequential_image_generation" type="string" default="disabled">
      순차 이미지 생성 모드(더우바오 전용 기능)

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

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

      **사용 안내:**

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

      **주의:**

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

    <ParamField body="metadata.sequential_image_generation_options" type="object">
      순차 이미지 생성 옵션

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

      **속성:**

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

      **예시:**

      ```json theme={null}
      "sequential_image_generation_options": { "max_images": 3 }
      ```
    </ParamField>

    <ParamField body="metadata.watermark" type="boolean" default={false}>
      생성 이미지에 워터마크를 추가할지 여부

      * `true`: 워터마크 추가
      * `false`: 워터마크 없음(기본값)
    </ParamField>
  </Expandable>
</ParamField>

## 응답

<ResponseField name="id" type="string">
  상태 조회에 사용하는 작업 고유 식별자
</ResponseField>

<ResponseField name="object" type="string">
  객체 유형, 항상 `generation.task`
</ResponseField>

<ResponseField name="model" type="string">
  사용한 모델 이름
</ResponseField>

<ResponseField name="status" type="string">
  작업 상태

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

<ResponseField name="progress" type="integer">
  작업 진행률(0-100)
</ResponseField>

<ResponseField name="created_at" type="integer">
  작업 생성 타임스탬프(Unix 타임스탬프)
</ResponseField>

<ResponseField name="metadata" type="object">
  작업 메타데이터
</ResponseField>

<ResponseField name="completed_at" type="integer">
  작업 완료 타임스탬프(Unix 타임스탬프). 작업이 완료된 뒤에만 반환됩니다.
</ResponseField>

<ResponseField name="expires_at" type="integer">
  결과 파일 만료 타임스탬프(Unix 타임스탬프). 만료 전에 결과 파일을 다운로드하거나 다른 곳에 저장하세요.
</ResponseField>

<ResponseField name="result" type="object">
  작업 성공 후의 생성 결과. `status` 가 `completed` 일 때만 반환됩니다.
</ResponseField>

<ResponseField name="result.type" type="string">
  결과 유형, 이미지 작업은 항상 `image` 입니다.
</ResponseField>

<ResponseField name="result.data" type="array">
  이미지 결과 목록. 레이어 분리를 활성화하면 첫 번째 요소가 보통 배경 이미지이고 나머지 요소가 투명 채널을 가진 독립 PNG 레이어입니다.
</ResponseField>

<ResponseField name="result.data[].url" type="string">
  배경 이미지 또는 독립 레이어의 공개 접근 주소입니다.
</ResponseField>

<ResponseField name="result.data[].z_index" type="integer">
  레이어 적층 순서. `layer_decomposition` 을 활성화하면 배경 이미지가 보통 `0` 이고 독립 레이어가 순서대로 증가합니다.
</ResponseField>

<ResponseField name="result.data[].size" type="string">
  현재 배경 이미지 또는 독립 레이어의 픽셀 크기입니다. 예: `2048x2048`.
</ResponseField>

<ResponseField name="result.data[].output_format" type="string">
  현재 결과 항목의 파일 형식입니다. 배경 이미지는 요청한 형식일 수 있고 투명 독립 레이어는 `png` 입니다.
</ResponseField>

<ResponseField name="result.data[].bounding_box" type="object">
  배경 이미지에서 독립 레이어의 위치이며 `absolute` 절대 좌표와 `normalized` 정규화 좌표를 포함합니다.
</ResponseField>

<ResponseField name="result.data[].bounding_box.absolute" type="array">
  배경 이미지에서 레이어의 절대 픽셀 좌표로 `[x1, y1, x2, y2]` 형식이며 각각 좌측 상단과 우측 하단 좌표를 나타냅니다.
</ResponseField>

<ResponseField name="result.data[].bounding_box.normalized" type="array">
  레이어의 정규화 좌표로 `[x1, y1, x2, y2]` 형식이며 좌표 범위는 `0-1000` 입니다.
</ResponseField>

<ResponseField name="result.data[].name" type="string">
  레이어 이름입니다.
</ResponseField>

<ResponseField name="result.data[].description" type="string">
  레이어 내용 설명입니다.
</ResponseField>

<RequestExample>
  ```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}` 로 전체 레이어 결과를 조회하세요.
  </Note>

  ```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}`);
  ```
</RequestExample>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>