> ## 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로 Dreamina Seedance 2.0 Fast 260128 사용하기

> Comfy Router를 통해 byteplus/dreamina-seedance-2-0-fast-260128을 호출합니다: endpoint, 요청 형태, 그리고 Router가 반환하는 응답을 설명합니다.

`byteplus/dreamina-seedance-2-0-fast-260128`에 대한 API 레퍼런스로, BytePlus에서 Comfy Router를 통해 제공됩니다.

## 빠른 시작

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

**모델 ID:** `byteplus/dreamina-seedance-2-0-fast-260128`

**엔드포인트:** `POST https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-0-fast-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/dreamina-seedance-2-0-fast-260128",
              {
                  "content": [
                      {
                          "text": "A red fox trotting through a snowy pine forest",
                          "type": "text",
                      },
                  ],
                  "duration": 5,
                  "ratio": "16:9",
                  "resolution": "720p",
              },
          )

      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/dreamina-seedance-2-0-fast-260128", {
        content: [
          {
            text: "A red fox trotting through a snowy pine forest",
            type: "text",
          },
        ],
        duration: 5,
        ratio: "16:9",
        resolution: "720p",
      });

      console.log(data);
      ```

      ```bash cURL theme={null}
      curl https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-0-fast-260128 \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"content\": [{\"text\":\"A red fox trotting through a snowy pine forest\",\"type\":\"text\"}], \"duration\": 5, \"ratio\": \"16:9\", \"resolution\": \"720p\"}"
      ```
    </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/dreamina-seedance-2-0-fast-260128",
              {
                  "content": [
                      {
                          "text": "A red fox trotting through a snowy pine forest",
                          "type": "text",
                      },
                  ],
                  "duration": 5,
                  "ratio": "16:9",
                  "resolution": "720p",
              },
          )
          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/dreamina-seedance-2-0-fast-260128", {
        content: [
          {
            text: "A red fox trotting through a snowy pine forest",
            type: "text",
          },
        ],
        duration: 5,
        ratio: "16:9",
        resolution: "720p",
      });
      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/dreamina-seedance-2-0-fast-260128/requests \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"content\": [{\"text\":\"A red fox trotting through a snowy pine forest\",\"type\":\"text\"}], \"duration\": 5, \"ratio\": \"16:9\", \"resolution\": \"720p\"}"

      # 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/dreamina-seedance-2-0-fast-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/dreamina-seedance-2-0-fast-260128/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 스키마

### 입력

<ParamField body="callback_url" type="string (uri)">
  이 생성 작업 결과에 대한 콜백 알림 주소입니다.

  형식: `uri`
</ParamField>

<ParamField body="content" type="object[]" required>
  모델이 비디오를 생성하기 위한 입력 콘텐츠입니다.
</ParamField>

<ParamField body="content[].audio_url" type="object">
  입력 오디오 객체입니다. Seedance 2.5, 2.0 및 2.0 fast만 오디오 입력을 지원합니다. Seedance 2.0 및 2.0 fast는 오디오만 단독으로 사용할 수 없으며, 최소 1개의 이미지 또는 비디오를 포함해야 합니다. Seedance 2.5는 오디오만 입력하는 것을 지원합니다.
</ParamField>

<ParamField body="content[].audio_url.url" type="string" required>
  오디오 URL, Base64 인코딩 또는 Asset ID입니다.
  오디오 URL: 오디오의 공개 URL입니다 (wav, mp3).
  Base64: 형식 data:audio/\<format>;base64,\<content>
  Asset ID: 형식 asset://\<ASSET\_ID>
</ParamField>

<ParamField body="content[].image_url" type="object" />

<ParamField body="content[].image_url.url" type="string" required>
  이미지 기반 비디오 생성을 위한 이미지 콘텐츠입니다 (type이 "image\_url"인 경우).
  이미지 URL: 이미지 URL에 접근할 수 있는지 확인하세요.
  Base64로 인코딩된 콘텐츠: 형식은 data:image/\<format>;base64,\<content>여야 합니다.
  Asset ID: 형식 asset://\<ASSET\_ID>
</ParamField>

<ParamField body="content[].role" type="string">
  콘텐츠 항목의 역할/위치입니다.
  이미지의 경우: first\_frame, last\_frame 또는 reference\_image.
  비디오의 경우: reference\_video (Seedance 2.5, 2.0 및 2.0 fast만).
  오디오의 경우: reference\_audio (Seedance 2.5, 2.0 및 2.0 fast만).

  가능한 값: `first_frame`, `last_frame`, `reference_image`, `reference_video`, `reference_audio`
</ParamField>

<ParamField body="content[].text" type="string">
  모델에 대한 입력 텍스트 정보입니다. 텍스트 프롬프트와 선택적 파라미터를 포함합니다.

  텍스트 프롬프트 (필수): 중국어 및 영어 문자를 사용하여 생성할 비디오에 대한 설명입니다.

  파라미터 (선택 사항): 텍스트 프롬프트 뒤에 --\[parameters]를 추가하여 비디오 사양을 제어합니다:

  * \--resolution (--rs): 480p, 720p, 1080p (기본값: 720p)
  * \--ratio (--rt): 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, 9:21, adaptive (기본값: 16:9 또는 adaptive)
  * \--duration (--dur): 3-12초 (기본값: 5)
  * \--framepersecond (--fps): 24 (기본값: 24)
  * \--watermark (--wm): true/false (기본값: false)
  * \--seed (--seed): -1 \~ 2^32-1 (기본값: -1)
  * \--camerafixed (--cf): true/false (기본값: false)

  예: "A beautiful landscape --ratio 16:9 --resolution 720p --duration 5"
</ParamField>

<ParamField body="content[].type" type="string" required>
  입력 콘텐츠의 유형입니다.

  가능한 값: `text`, `image_url`, `video_url`, `audio_url`
</ParamField>

<ParamField body="content[].video_url" type="object">
  입력 비디오 객체입니다. Seedance 2.5, 2.0 및 2.0 fast만 비디오 입력을 지원합니다.
</ParamField>

<ParamField body="content[].video_url.url" type="string" required>
  비디오 URL 또는 Asset ID입니다.
  비디오 URL: 비디오의 공개 URL입니다 (mp4, mov).
  Asset ID: 형식 asset://\<ASSET\_ID>
</ParamField>

<ParamField body="duration" type="`-1` | object">
  비디오 재생 시간(초)입니다. Seedance 2.5: \[4,30] 또는 -1 (자동, 비디오 편집 작업은 -1만 지원). Seedance 2.0 및 2.0 fast: \[4,15] 또는 -1 (자동). Seedance 1.5 pro: \[4,12] 또는 -1. Seedance 1.0: \[2,12].

  범위: `2` \~ `30`
</ParamField>

<ParamField body="execution_expires_after" type="integer">
  작업 타임아웃 임계값(초)입니다. 기본값 172800 (48시간). 범위: \[3600, 259200].

  범위: `3600` \~ `259200`
</ParamField>

<ParamField body="generate_audio" type="boolean" default="true">
  Seedance 2.5, 2.0, 2.0 fast 및 1.5 pro에서 지원됩니다. 생성된 비디오에 시각 요소와 동기화된 오디오가 포함되는지 여부입니다.
  true: 모델이 동기화된 오디오가 포함된 비디오를 출력합니다.
  false: 모델이 무음 비디오를 출력합니다.
</ParamField>

<ParamField body="model" type="string">
  호출할 모델의 ID입니다. 지원되는 모델: seedance-1-5-pro-251215, seedance-1-0-pro-250528, seedance-1-0-pro-fast-251015, seedance-1-0-lite-t2v-250428, seedance-1-0-lite-i2v-250428, dreamina-seedance-2-0-260128, dreamina-seedance-2-0-fast-260128, dreamina-seedance-2-0-mini 및 dreamina-seedance-2-5-260628. POST /proxy/byteplus/api/v3/contents/generations/tasks에 대한 직접 v1 호출은 반드시 이 값을 제공해야 합니다. 프록시는 다른 값이나 값을 생략한 경우 400으로 거부합니다. 이 스키마의 `required` 목록에 없는 이유는 Comfy Router가 /v2/models/byteplus/\{model}의 `{model}` 경로 세그먼트에서 이 값을 채우기 때문에 Router 호출자는 이를 생략하기 때문입니다.
</ParamField>

<ParamField body="output_format" type="string" default="&#x22;mp4&#x22;">
  Seedance 2.5 전용입니다. 출력 비디오의 컨테이너 형식입니다.
  mp4: 범용 컨테이너(H.264/AAC, yuv420p)로 호환성이 넓고 파일 크기가 더 작습니다.
  mov: 전문가용 컨테이너(H.264 High 4:4:4 Predictive/PCM, yuv444p)로 색상 정밀도가 높아 후반 작업에 적합하며 파일 크기가 더 큽니다.

  가능한 값: `mp4`, `mov`
</ParamField>

<ParamField body="ratio" type="string">
  생성된 비디오의 화면 비율입니다. Seedance 2.0 및 2.0 fast, 1.5 pro 기본값: adaptive.

  가능한 값: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `9:21`, `adaptive`
</ParamField>

<ParamField body="resolution" type="string">
  비디오 해상도입니다. Seedance 2.5, 2.0 및 2.0 fast, 1.5 pro, 1.0 lite 기본값: 720p. Seedance 1.0 pro 및 pro-fast 기본값: 1080p.
  참고: Seedance 2.0 및 2.0 fast는 1080p를 지원하지 않습니다. Seedance 2.5는 480p, 720p 및 1080p를 지원합니다.

  가능한 값: `480p`, `720p`, `1080p`, `4k`
</ParamField>

<ParamField body="return_last_frame" type="boolean" default="false">
  생성된 비디오의 마지막 프레임 이미지를 반환할지 여부입니다.true: 생성된 비디오의 마지막 프레임 이미지를 반환합니다. 이 매개변수를 true로 설정하면 비디오 생성 작업 정보 조회를 호출하여 마지막 프레임 이미지를 얻을 수 있습니다. 마지막 프레임 이미지는 PNG 형식이며, 픽셀 너비와 높이는 생성된 비디오와 동일하고 워터마크가 포함되지 않습니다. 이 매개변수를 사용하면 여러 개의 연속된 비디오를 생성할 수 있습니다. 이전에 생성된 비디오의 마지막 프레임을 다음 비디오 작업의 첫 프레임으로 사용하여 여러 개의 연속된 비디오를 빠르게 생성할 수 있습니다.
  false: 생성된 비디오의 마지막 프레임 이미지를 반환하지 않습니다.
</ParamField>

<ParamField body="seed" type="integer">
  무작위성을 제어하기 위한 시드 정수입니다. 범위: \[-1, 2^32-1]. -1은 무작위 시드를 사용합니다.

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

<ParamField body="service_tier" type="string">
  처리에 사용할 서비스 등급입니다. Seedance 2.5, 2.0 및 2.0 fast는 flex(오프라인 추론)를 지원하지 않습니다.

  사용 가능한 값: `default`, `flex`
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  생성된 비디오에 워터마크가 포함되는지 여부입니다.
</ParamField>

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

### 출력

<ResponseField name="content" type="object">
  비디오 생성 작업이 완료된 후의 출력입니다. 출력 비디오의 다운로드 URL과, BytePlus가 반환하는 경우 마지막 프레임의 다운로드 URL을 포함합니다. `video_url`과 `last_frame_url`은 모두 Comfy 스토리지에 다시 호스팅되며, 여기의 다른 모든 필드는 BytePlus 자체 필드입니다. null일 수 있습니다: BytePlus는 작업 후 24시간이 지나면 URL을 지우므로, 그 이후에 폴링한 성공 문서는 `content`가 없거나 null일 수 있습니다.
</ResponseField>

<ResponseField name="content.last_frame_url" type="string">
  생성된 비디오의 마지막 프레임에 대한 다운로드 URL로, 요청에서 `return_last_frame`을 설정한 경우 반환됩니다. 이 URL에서 이미지 형식을 추론하지 마세요. BytePlus는 요청 측에서 마지막 프레임을 PNG로 문서화하고, Router는 제공받은 바이트를 그대로 다시 호스팅하며 업스트림 Content-Type 또는 콘텐츠 스니핑을 통해 형식을 지정합니다. `image/jpeg`는 둘 다 실패했을 때의 최후 수단 폴백일 뿐입니다. Router는 마지막 프레임을 Comfy 스토리지에 다시 호스팅하고 이 필드를 다시 작성하므로, 일반적으로 최대 24시간 동안 유효한 Comfy 서명 URL입니다. 발급 시 24시간으로 서명되고 23시간 메모에서 재생되므로, 나중에 폴링하면 남은 시간이 1시간도 되지 않는 URL이 반환될 수 있습니다. 다시 호스팅을 수행할 수 없었던 경우에는 이 필드가 BytePlus 자체 URL을 유지하며, BytePlus는 작업 후 24시간이 지나면 이를 지웁니다. 어느 경우든 링크는 만료되므로 URL을 저장하지 말고 프레임을 다운로드하세요.
</ResponseField>

<ResponseField name="content.output_format" type="string">
  BytePlus가 `content` 안에 중첩해 반환할 때의 생성된 비디오의 컨테이너 형식(mp4 또는 mov)입니다. Seedance 모델은 이를 `content`의 최상위 형제 필드로 반환하는 경우가 더 많습니다. 최상위 `output_format` 필드를 참조하세요. Router는 둘 중 존재하는 것을 읽습니다.
</ResponseField>

<ResponseField name="content.video_url" type="string">
  출력 비디오의 다운로드 URL입니다. Router는 비디오를 Comfy 스토리지에 다시 호스팅하고 이 필드를 다시 작성하므로, 일반적으로 최대 24시간 동안 유효한 Comfy 서명 URL입니다. 발급 시 24시간으로 서명되고 23시간 메모에서 재생되므로, 나중에 폴링하면 남은 시간이 1시간도 되지 않는 URL이 반환될 수 있습니다. 다시 호스팅을 수행할 수 없었던 경우에는 이 필드가 BytePlus 자체 URL을 유지하며, BytePlus는 작업 후 24시간이 지나면 이를 지우고 일부 모델에서는 다운로드를 100회로 제한합니다. 어느 경우든 링크는 만료되므로 URL을 저장하지 말고 비디오를 다운로드하세요.
</ResponseField>

<ResponseField name="created_at" type="integer">
  작업이 생성된 시간입니다. 값은 초 단위의 UNIX 타임스탬프입니다.
</ResponseField>

<ResponseField name="duration" type="number">
  생성된 비디오의 재생 시간(초)입니다. BytePlus가 이 값에 대해 일관성이 없기 때문에 정수가 아닌 숫자로 선언됩니다. 비디오 작업은 정수 초를 반환한 것으로 관찰되었고, 이와 유사한 다른 BytePlus 인터페이스는 소수 재생 시간을 보고합니다. 따라서 클라이언트는 값이 정수라고 가정해서는 안 됩니다. BytePlus 자체 필드로, 성공한 비디오 작업에서 반환되며 변경 없이 전달됩니다.
</ResponseField>

<ResponseField name="error" type="object">
  오류 정보입니다. 작업이 성공하면 null이 반환됩니다. 작업이 실패하면 오류 정보가 반환됩니다.
</ResponseField>

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

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

<ResponseField name="id" type="string">
  비디오 생성 작업의 ID
</ResponseField>

<ResponseField name="model" type="string">
  작업에 사용된 모델의 이름과 버전
</ResponseField>

<ResponseField name="output_format" type="string">
  생성된 비디오의 컨테이너 형식(mp4 또는 mov)으로, `content`의 형제로 최상위에 반환됩니다. Seedance 비디오 작업 조회가 반환하는 위치입니다. BytePlus 자체 필드로, 변경 없이 전달됩니다.
</ResponseField>

<ResponseField name="resolution" type="string">
  생성된 비디오의 해상도(예: `1080p`)입니다. BytePlus 자체 필드로, 성공한 비디오 작업에서 반환되며 변경 없이 전달됩니다.
</ResponseField>

<ResponseField name="seed" type="integer">
  작업에 실제로 사용된 생성 시드입니다. BytePlus 자체 필드로, 성공한 비디오 작업에서 반환되며 변경 없이 전달됩니다.

  형식: `int64`
</ResponseField>

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

  가능한 값: `queued`, `running`, `cancelled`, `succeeded`, `failed`, `expired`
</ResponseField>

<ResponseField name="updated_at" type="integer">
  작업이 마지막으로 업데이트된 시간입니다. 값은 초 단위의 UNIX 타임스탬프입니다.
</ResponseField>

<ResponseField name="usage" type="object">
  요청의 토큰 사용량
</ResponseField>

<ResponseField name="usage.completion_tokens" type="integer">
  모델이 생성한 토큰 수
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  비디오 생성 모델의 경우 입력 토큰 수는 계산되지 않고 0으로 기본 설정됩니다. 따라서 total\_tokens = completion\_tokens입니다.
</ResponseField>

## 예시

### 입력

```json theme={null}
{
  "content": [
    {
      "text": "A red fox trotting through a snowy pine forest",
      "type": "text"
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p"
}
```

### 출력

```json theme={null}
{
  "content": {
    "last_frame_url": "https://example.invalid/byteplus/seedance-1-0-lite-t2v-250428/last-frame",
    "video_url": "https://example.invalid/byteplus/seedance-1-0-lite-t2v-250428/generated.mp4"
  },
  "created_at": 1767225600,
  "duration": 5,
  "error": null,
  "id": "3f7a1b28-5c0d-4e91-8a6f-1b2c3d4e5f60",
  "model": "dreamina-seedance-2-0-fast-260128",
  "output_format": "mp4",
  "resolution": "1080p",
  "seed": 1234567890123,
  "status": "succeeded",
  "updated_at": 1767225730
}
```

## 배포 전 확인

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>