> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-chore-sync-comfy-api-v2-spec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Router로 Seedream 5.0 260128 사용하기

> Comfy Router를 통해 byteplus/seedream-5-0-260128을 호출합니다: 엔드포인트, 요청 형태, 그리고 Router가 반환하는 응답.

Comfy Router가 BytePlus에서 제공하는 `byteplus/seedream-5-0-260128`에 대한 API 레퍼런스입니다.

## 빠른 시작

[Comfy 워크스페이스](https://platform.comfy.org/profile/api-keys)에서 키를 생성하고 `COMFY_API_KEY`로 내보내세요. Python 및 TypeScript 스니펫은 Comfy SDKs (`pip install comfy-sdk`, `npm install @comfyorg/sdk`)를 사용합니다. cURL 스니펫은 원시 HTTP를 통한 동일한 호출입니다.

**모델 ID:** `byteplus/seedream-5-0-260128`

**엔드포인트:** `POST https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128`

<Tabs>
  <Tab title="Wait for the result">
    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # Reads COMFY_API_KEY from the environment.
      # The SDK automatically creates an idempotency key and reuses it for automatic retries.
      with Comfy() as client:
          result = client.models.run(
              "byteplus/seedream-5-0-260128",
              {
                  "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
                  "response_format": "url",
                  "watermark": False,
              },
          )

      print(result)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // Reads COMFY_API_KEY from the environment.
      // The SDK automatically creates an idempotency key and reuses it for automatic retries.
      const { data } = await comfy.models.run("byteplus/seedream-5-0-260128", {
        prompt: "A red fox trotting through a snowy pine forest, cinematic lighting",
        response_format: "url",
        watermark: false,
      });

      console.log(data);
      ```

      ```bash cURL theme={null}
      curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128 \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"prompt\": \"A red fox trotting through a snowy pine forest, cinematic lighting\", \"response_format\": \"url\", \"watermark\": false}"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Queue and collect later">
    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # Reads COMFY_API_KEY from the environment.
      # Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
      with Comfy() as client:
          handle = client.models.submit(
              "byteplus/seedream-5-0-260128",
              {
                  "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
                  "response_format": "url",
                  "watermark": False,
              },
          )
          print("request_id:", handle.request_id)  # with the model ID, all another process needs

          # Poll until the request completes, waiting the Retry-After the server names.
          for update in handle.iter_events():
              print(update.status, update.queue_position)

          # The provider's own payload, the same value models.run() returns.
          # A request that failed or was cancelled raises the typed Router error here.
          result = handle.get()

      print(result)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // Reads COMFY_API_KEY from the environment.
      // Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
      const handle = await comfy.models.submit("byteplus/seedream-5-0-260128", {
        prompt: "A red fox trotting through a snowy pine forest, cinematic lighting",
        response_format: "url",
        watermark: false,
      });
      console.log("requestId:", handle.requestId); // with the model ID, all another process needs

      // Poll until the request completes, waiting the Retry-After the server names.
      for await (const update of handle.events()) {
        console.log(update.status, update.queuePosition);
      }

      // The same result models.run() returns. A request that failed or was cancelled rejects here.
      const result = await handle.get();

      console.log(result.data);
      ```

      ```bash cURL theme={null}
      # 1. Submit. Router answers 201 with request_id, status_url, response_url and cancel_url.
      curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"prompt\": \"A red fox trotting through a snowy pine forest, cinematic lighting\", \"response_format\": \"url\", \"watermark\": false}"

      # 2. Poll until status is COMPLETED, waiting the Retry-After seconds each response names.
      REQUEST_ID="<request_id from the 201 body>"
      curl -i https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests/$REQUEST_ID/status \
        -H "X-API-Key: $COMFY_API_KEY"

      # 3. Collect. 200 with the model's native output, 202 with the status body while it is still running.
      curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Schema

### Input

<ParamField body="guidance_scale" type="number">
  출력 이미지가 입력 프롬프트에 얼마나 밀접하게 부합하는지 제어합니다. 범위 \[1, 10]. 값이 높을수록 프롬프트 준수가 강해집니다. seedream-3-0-t2i-250415의 기본값은 2.5이고 seededit-3-0-i2i-250628의 기본값은 5.5입니다. seedream-5.0-pro, 5.0-lite, 4.5 및 4.0에서는 지원되지 않습니다.

  범위: `1` \~ `10`

  형식: `실수`
</ParamField>

<ParamField body="image" type="string | string[]">
  Seedream-5.0-pro, 5.0-lite, 4.5, 4.0 및 seededit-3.0-i2i가 이 매개변수를 지원합니다.

  편집할 이미지의 Base64 인코딩 또는 접근 가능한 URL을 입력하세요. Seedream-5.0-pro, 5.0-lite, 4.5, 4.0은 단일 이미지 또는 여러 이미지 입력을 지원하며(다중 이미지 블렌딩 예제 참조), seededit-3.0-i2i는 단일 이미지 입력만 지원합니다.

  • 이미지 URL: 이미지 URL에 접근할 수 있는지 확인하세요.
  • Base64 인코딩: 형식은 data:image/\<image format>;base64,\<Base64 encoding>이어야 합니다. 참고: \<image format>은 소문자여야 합니다. 예: data:image/png;base64,\<base64\_image>.

  Comfy Router는 base64 확장과 모든 참조 이미지를 포함하여 전체 JSON 요청을 10 MiB로 제한합니다. 이 전송 한도를 초과하는 입력에는 URL을 사용하세요.

  입력 이미지는 다음 요구 사항을 충족해야 합니다:
  • 이미지 형식: jpeg, png (seedream-5.0-pro, 5.0-lite, 4.5, 4.0은 webp, bmp, tiff, gif도 지원하며, seedream-5.0-pro는 heic와 heif도 지원합니다)
  • 가로세로 비율(너비/높이): seedream-5.0-pro, 5.0-lite, 4.5, 4.0의 경우 \[1/16, 16] 범위, seededit-3.0-i2i의 경우 \[1/3, 3] 범위
  • 너비와 높이(px): > 14
  • 크기: 10 MB 이하 (seedream-5.0-pro의 경우 30 MB)
  • 총 픽셀: seedream-5.0-pro의 경우 6000x6000 (36,000,000 px) 이하
  • 참조 이미지 최대 14개 (seedream-5.0-pro의 경우 10개)

  레이어 분리 시나리오(layer\_decomposition 활성화)에서는 image가 필수이며 단일 입력 이미지만 지원됩니다(여러 이미지를 전달하면 오류가 반환됩니다). 입력 이미지는 png, jpeg, webp, bmp, tiff 또는 gif여야 하며(heic와 heif는 지원되지 않음), 최대 30 MB이고 총 픽셀이 \[512x512, 6000x6000] 범위, 가로세로 비율이 \[1/16, 16] 범위여야 합니다.
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default="false">
  레이어 분리 활성화 여부를 제어합니다. seedream-5.0-pro만 이 매개변수를 지원합니다.
  true: 레이어 분리 모드입니다. 모델은 단일 입력 이미지를 하나의 기본 이미지와 여러 레이어(최대 16개)로 분해하고, 생성된 각 레이어의 위치 및 콘텐츠 정보를 반환합니다. 여기에는 쌓이는 순서(z\_index), 바운딩 박스(bounding\_box), 이름(name), 설명(description)이 포함됩니다.
  false: 표준 이미지 생성 모드이며 레이어 분리를 수행하지 않습니다.
  레이어 분리 모드 참고 사항: 단일 입력 이미지만 지원합니다(여러 이미지를 전달하면 오류가 반환됩니다). 단일 레이어라도 생성에 실패하면 전체 요청이 실패합니다. 부분 성공은 지원되지 않습니다. 최대 17개의 이미지가 반환됩니다(기본 이미지 1개 + 레이어 16개). sequential\_image\_generation, sequential\_image\_generation\_options, tools, stream을 전달하면 오류가 반환됩니다.
</ParamField>

<ParamField body="model" type="string">
  모델 식별자입니다. 지원되는 모델: seedream-3-0-t2i-250415, seededit-3-0-i2i-250628, seedream-4-0-250828, seedream-4-5-251128, seedream-5-0-260128, seedream-5-0-pro-260628. POST /proxy/byteplus/api/v3/images/generations에 대한 직접 v1 호출은 반드시 이 값을 제공해야 합니다. 프록시는 다른 값이나 누락된 값을 400으로 거부합니다. 이 스키마의 `required` 목록에 없는 이유는 Comfy Router가 /v2/models/byteplus/\{model}의 `{model}` 경로 세그먼트에서 값을 채우기 때문이며, 따라서 Router 호출자는 이를 생략합니다.
</ParamField>

<ParamField body="optimize_prompt_options" type="object">
  프롬프트 최적화 기능에 대한 구성입니다. seedream-5.0-pro/5.0-lite/4.5(standard 모드만 지원)와 seedream-4.0만 이 매개변수를 지원합니다.
</ParamField>

<ParamField body="optimize_prompt_options.mode" type="string" default="&#x22;standard&#x22;">
  프롬프트 최적화 기능의 모드를 설정합니다. standard = 더 높은 품질, 더 긴 생성 시간. fast = 더 빠르지만 평균 수준의 품질.

  가능한 값: `standard`, `fast`
</ParamField>

<ParamField body="output_format" type="string" default="&#x22;jpeg&#x22;">
  출력 이미지의 형식을 지정합니다. seedream-5.0-pro와 5.0-lite만 이 매개변수를 지원합니다. 레이어 분리 시나리오에서 output\_format은 기본 이미지의 형식만 제어하며, 모든 레이어는 항상 png로 출력됩니다.

  가능한 값: `png`, `jpeg`
</ParamField>

<ParamField body="prompt" type="string">
  이미지 생성 또는 변환을 위한 텍스트 설명입니다.
  레이어 분리 시나리오(layer\_decomposition이 활성화된 seedream-5.0-pro)에서는 선택 사항입니다. 프롬프트를 제공하면 모델이 프롬프트 의도에 따라 지정한 요소를 인식하고 분리합니다. 프롬프트를 제공하지 않으면 모델이 이미지의 모든 주요 요소를 자동으로 감지하여 독립적인 레이어로 분리합니다.
</ParamField>

<ParamField body="response_format" type="string" default="&#x22;url&#x22;">
  응답으로 반환되는 생성 이미지의 형식을 지정합니다

  가능한 값: `url`, `b64_json`
</ParamField>

<ParamField body="seed" type="integer" default="-1">
  이미지 생성의 무작위성을 제어하는 랜덤 시드입니다. 범위: \[-1, 2147483647]. 지정하지 않으면 시드가 자동으로 생성됩니다. 동일한 출력을 재현하려면 동일한 시드 값을 사용하세요.

  범위: `-1` \~ `2147483647`
</ParamField>

<ParamField body="sequential_image_generation" type="string">
  배치 생성 기능을 비활성화할지 여부를 제어합니다. 이 매개변수는 seedream-5.0-lite, 4.5, 4.0에서만 지원됩니다(seedream-5.0-pro에서는 지원되지 않습니다). 유효한 값:
  auto: 자동 모드에서는 모델이 사용자의 프롬프트를 기반으로 여러 이미지를 반환할지 여부와 포함할 이미지 수를 자동으로 결정합니다.
  disabled: 배치 생성 기능을 비활성화합니다. 모델은 이미지 하나만 생성합니다.

  가능한 값: `auto`, `disabled`
</ParamField>

<ParamField body="sequential_image_generation_options" type="object">
  seedream-5.0-lite, 4.5, 4.0만 이 파라미터를 지원합니다(seedream-5.0-pro는 지원하지 않음).
  배치 이미지 생성 기능 설정입니다. 이 파라미터는 sequential\_image\_generation이 auto로 설정된 경우에만 적용됩니다.
</ParamField>

<ParamField body="sequential_image_generation_options.max_images" type="integer" default="15">
  이 요청에서 생성할 최대 이미지 수를 지정합니다. 입력 참조 이미지 수 + 생성된 이미지 수 ≤ 15.

  범위: `1` \~ `15`
</ParamField>

<ParamField body="size" type="string">
  "seedream-3-0-t2i-250415": 생성된 이미지의 크기(너비 x 높이, 픽셀)를 지정합니다. \[512x512, 2048x2048] 범위여야 합니다.
  "seededit-3-0-i2i-250628": 생성된 이미지의 너비와 높이 픽셀입니다. 현재는 adaptive만 지원합니다.
  "seedream-4-0-250828": 생성할 이미지의 사양을 설정합니다. 두 가지 방법을 사용할 수 있지만 함께 사용할 수는 없습니다.
  방법 1 | 해상도를 지정합니다. 선택 가능한 값: 1K, 2K, 4K
  방법 2 | 너비와 높이를 픽셀로 지정합니다. 기본값: 2048x2048, 총 픽셀: \[1024x1024, 4096x4096], 가로세로 비율: \[1/16, 16]
  "seedream-4-5-251128": 두 가지 방법을 사용할 수 있습니다.
  방법 1 | 해상도를 지정합니다. 선택 가능한 값: 2K, 4K
  방법 2 | 너비와 높이를 픽셀로 지정합니다. 기본값: 2048x2048, 총 픽셀: \[2560x1440, 4096x4096], 가로세로 비율: \[1/16, 16]
  "seedream-5-0-260128": 두 가지 방법을 사용할 수 있습니다.
  방법 1 | 해상도를 지정합니다. 선택 가능한 값: 2K, 3K
  방법 2 | 너비와 높이를 픽셀로 지정합니다. 기본값: 2048x2048, 총 픽셀: \[2560x1440, \~3072x3072], 가로세로 비율: \[1/16, 16]
  "seedream-5-0-pro-260628": 두 가지 방법을 사용할 수 있습니다(함께 사용할 수 없음).
  방법 1 | 해상도를 지정하고 프롬프트에 이미지의 가로세로 비율, 형태 또는 용도를 설명합니다. 최종 크기는 모델이 결정합니다. 선택 가능한 값: 1K, 2K
  방법 2 | 너비와 높이를 픽셀로 지정합니다. 기본값: 1024x1024, 총 픽셀: \[1024x1024 (1048576), 2048x2048 (4194304)], 가로세로 비율: \[1/16, 16]
  layer\_decomposition이 활성화된 "seedream-5-0-pro-260628": 해상도 수준의 방법만 지원합니다. 선택 가능한 값: 1K, 1.5K, 2K, auto. 기본값: auto.
  기본 이미지는 원본 입력 이미지의 가로세로 비율로 지정된 해상도에 출력되며, 각 레이어는 원본 이미지에서 가지던 가로세로 비율을 유지한 채 지정된 해상도에 가깝게 출력됩니다.
  auto: 입력 이미지의 크기와 가로세로 비율을 기준으로 출력합니다. \[1280x720, \~2048x2048] 범위의 입력은 원본 입력 크기로 출력되고, 1K보다 작은 입력은 1K로 출력되며, 2K보다 큰 입력은 2K로 출력됩니다.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Comfy Router는 완전한 JSON 결과를 수집하기 때문에 명시적으로 전달된 stream 플래그를 거짓으로 고정합니다. v1 프록시에서는 이 필드가 스트리밍 출력 모드를 활성화할지 여부를 제어합니다. seedream-5.0-lite, 4.5, 4.0만 이 파라미터를 지원합니다(seedream-5.0-pro는 지원하지 않음). 거짓 = 모든 출력 이미지가 한 번에 반환됩니다. 참 = 각 출력 이미지가 생성된 직후 즉시 반환됩니다.
</ParamField>

<ParamField body="watermark" type="boolean" default="true">
  생성된 이미지에 워터마크를 추가할지 여부를 지정합니다. 거짓 = 워터마크 없음, 참 = 'AI generated' 라벨이 있는 워터마크 추가
</ParamField>

Router가 `GET /v2/models/byteplus/seedream-5-0-260128/openapi.json`에서 제공하는 스키마를 기반으로 생성되었으며, 이는 요청이 공급자에 도달하기 전에 호출을 검증할 때 사용하는 것과 동일한 문서입니다.

### 출력

<ResponseField name="created" type="integer">
  요청이 생성된 시각을 나타내는 Unix 타임스탬프(초 단위)
</ResponseField>

<ResponseField name="data" type="object[]">
  생성된 이미지에 대한 정보를 담고 있습니다.
  레이어 분리 시나리오에서는 배열의 첫 번째 요소가 기본 이미지(z\_index=0)이고, 그 뒤의 요소들은 z\_index가 증가하는 순서로 정렬된 레이어입니다.
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  Base64로 인코딩된 이미지 데이터(response\_format이 "b64\_json"인 경우)
</ResponseField>

<ResponseField name="data[].bounding_box" type="object">
  현재 레이어가 기본 이미지 내에서 차지하는 영역의 바운딩 박스 정보입니다. 레이어만 이 필드를 반환하며, 기본 이미지는 전체 캔버스를 차지하므로 bounding\_box를 반환하지 않습니다. layer\_decomposition이 true인 경우에만 반환됩니다.
</ResponseField>

<ResponseField name="data[].bounding_box.absolute" type="integer[]">
  좌측 상단 모서리를 (0, 0)으로 하는 출력 기본 이미지의 좌표계에서 레이어 바운딩 박스의 절대 픽셀 좌표입니다. 좌표 형식: \[left, top, right, bottom].
</ResponseField>

<ResponseField name="data[].bounding_box.normalized" type="integer[]">
  기본 이미지 크기를 기준으로 \[0, 1000]의 이산 정수 범위에 비례적으로 매핑되고 최대 1000에서 잘린, 레이어 바운딩 박스의 천분율(per-mille) 양자화(정규화) 좌표입니다. 좌표 형식: \[left, top, right, bottom].
</ResponseField>

<ResponseField name="data[].description" type="string">
  현재 분리된 요소에 대한 상세 설명으로, name보다 풍부한 레이어 특성(색상, 상태, 재질 등)을 제공합니다. 레이어만 이 필드를 반환하며, 기본 이미지는 반환하지 않습니다. layer\_decomposition이 true인 경우에만 반환됩니다.
</ResponseField>

<ResponseField name="data[].name" type="string">
  현재 분리된 요소의 이름/레이블로, 분리된 피사체의 특성으로부터 모델이 자동으로 생성합니다. 레이어만 이 필드를 반환하며, 기본 이미지는 반환하지 않습니다. layer\_decomposition이 true인 경우에만 반환됩니다.
</ResponseField>

<ResponseField name="data[].output_format" type="string">
  출력 이미지의 파일 형식입니다. seedream-5.0-pro만 이 필드를 지원합니다.
</ResponseField>

<ResponseField name="data[].size" type="string">
  이미지의 너비와 높이(픽셀)이며, \<width>x\<height> 형식입니다. seedream-5.0-pro, 5.0-lite, 4.5 및 4.0만 이 매개변수를 지원합니다.
</ResponseField>

<ResponseField name="data[].url" type="string (uri)">
  이미지 다운로드용 URL(response\_format이 "url"인 경우)

  형식: `uri`
</ResponseField>

<ResponseField name="data[].z_index" type="integer">
  레이어의 적층 순서로, 아래에서 위로 갈수록 증가합니다. 0은 가장 아래 레이어(기본 이미지)이고, 값이 클수록 위에 위치합니다. 레이어를 올바른 적층 순서로 재구성하여 완전한 이미지로 만들 때 사용합니다. layer\_decomposition이 true인 경우에만 반환됩니다.
</ResponseField>

<ResponseField name="error" type="object">
  오류 정보(있는 경우)
</ResponseField>

<ResponseField name="error.code" type="string">
  오류 코드
</ResponseField>

<ResponseField name="error.message" type="string">
  오류 메시지
</ResponseField>

<ResponseField name="model" type="string">
  요청에 사용된 모델 ID
</ResponseField>

<ResponseField name="usage" type="object" />

<ResponseField name="usage.generated_images" type="integer">
  모델이 생성한 이미지 수
</ResponseField>

<ResponseField name="usage.input_images" type="integer">
  모델에 입력된 이미지 수입니다. seedream-5.0-pro만 이 필드를 지원합니다.
</ResponseField>

<ResponseField name="usage.output_tokens" type="integer">
  모델이 생성한 그림에 사용된 토큰 수입니다.
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  이 요청에서 소비된 총 토큰 수입니다.
</ResponseField>

## 예시

### 입력

```json theme={null}
{
  "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
  "response_format": "url",
  "watermark": false
}
```

### 출력

```json theme={null}
{
  "created": 1767225600,
  "data": [
    {
      "size": "1024x1024",
      "url": "https://example.invalid/byteplus/seedream-3-0-t2i-250415/generated.png"
    }
  ],
  "model": "seedream-5-0-260128",
  "usage": {
    "generated_images": 1
  }
}
```

## 배포 전 확인

SDK는 `Idempotency-Key`를 생성하고 자동 재시도에서 재사용합니다. 수동 재시도 시에는 원래 키를 재사용하세요. Router는 연결을 최대 10분간 유지할 수 있습니다.

요청이 실패하면 Router는 이유를 설명하는 `X-Comfy-Error-Type` 응답 헤더를 보냅니다. `422`는 Router가 프로바이더를 호출하기 전에 입력을 거부했음을 의미합니다. 생성된 에셋은 [결과 URL이 만료](/ko/development/comfy-router/reference#결과-에셋)될 수 있으므로 즉시 다운로드하세요.

<CardGroup cols={3}>
  <Card title="헤더" icon="list" href="/ko/development/comfy-router/quickstart">
    인증, 멱등성, 요청 ID, 오류 분류, 재시도 간격, 지출 한도.
  </Card>

  <Card title="Router API 사용" icon="code" href="/ko/development/comfy-router/quickstart">
    모델 검색, 유효성 검사 오류, 재시도, 과금.
  </Card>

  <Card title="제한 사항" icon="triangle-exclamation" href="/ko/development/comfy-router/limitations">
    Router가 현재 지원하지 않는 기능과 대체 방법.
  </Card>
</CardGroup>