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

# 에셋 우선: 더 빠르고 안정적인 이미지 및 동영상 입력

> 이미지 또는 동영상이 포함된 Seedance 호출에서는 create-task 엔드포인트가 작업 ID를 반환하는 데 수십 초가 걸리거나 클라이언트에서 시간 초과가 발생할 수 있습니다. 먼저 미디어를 수집하여 asset:// ID를 받은 다음 대신 이를 참조하십시오. 그러면 요청 본문이 메가바이트에서 수십 바이트로 줄어들고 제출이 즉시 반환되며 콘텐츠 검사가 수집 시점으로 앞당겨집니다. 지연 시간 분석, 시간 초과 후 수행할 작업, 마이그레이션 단계가 포함되어 있습니다.

<Note>
  **간단히 말하면**: 텍스트-동영상은 영향을 받지 않으며 약 1초 만에 작업 ID를 반환합니다. **요청에 이미지 또는 동영상이 포함되는 순간, 먼저 미디어를 자산 라이브러리로 수집하고 `asset://` 자산 ID를 받은 다음 생성 요청에서 해당 ID를 참조해야 합니다.** 요청 본문은 메가바이트 단위에서 수십 바이트로 줄어들고, 작업 생성 엔드포인트는 즉시 반환되며, 미디어의 콘텐츠 검사는 대신 수집 시점에 수행됩니다.

  이 페이지에서는 **제출** 속도와 안정성을 다룹니다. 자산 라이브러리의 엔드포인트별 문서는 [자산 라이브러리](/ko/api-capabilities/seedance2/asset-library)를 참조하고, 처음부터 끝까지 실행할 수 있는 코드는 [자산 참조 가이드](/ko/api-capabilities/seedance2/asset-reference)를 참조하시기 바랍니다.
</Note>

## 먼저 확인할 사항: 제출이 느린 것입니까, 아니면 생성이 느린 것입니까?

Seedance는 **비동기 태스크 기반** API입니다. 하나의 클립은 서로 다른 두 단계로 구성되며, 각 단계의 지연 시간은 완전히 다른 원인에서 발생합니다.

| 단계                                                          | 반환되는 항목                     | 일반적인 소요 시간                                     | 느려지는 이유                                                                                          |
| ----------------------------------------------------------- | --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **1. 제출**: `POST .../generations/tasks`                     | 태스크 ID, `{"id": "cgt-..."}` | 텍스트-동영상 변환은 약 1초이며, 미디어가 첨부되면 미디어 크기에 따라 증가합니다 | 미디어가 먼저 APIYI로 업로드된 다음 Volcengine으로 전달되고, 해당 서버에서 디코딩 및 검증되어야 합니다. 이 모든 과정이 끝난 후에야 태스크 ID가 반환됩니다 |
| **2. 생성**: `GET .../tasks/{id}`을 폴링하여 `succeeded`이 될 때까지 대기 | 완성된 클립, `content.video_url` | 일반적으로 **2\~5분**(1080p 또는 긴 재생 시간에서는 더 오래 걸립니다) | 제공업체 측 큐 대기 및 추론 때문이며, 이는 정상적인 속도입니다                                                             |

**두 단계는 서로 독립적입니다.** 제출에 60초가 걸린 것과 생성에 5분이 걸린 것은 서로 다른 문제이므로, 무엇이 느린지 먼저 확인한 후 변경해야 합니다. 콘솔 로그의 기간 열은 **첫 바이트까지 걸린 시간**이며, 1단계에 해당합니다. 클립을 완성하는 데 걸리는 전체 시간은 아닙니다. [콘솔 기간과 클라이언트 대기 시간](/ko/faq/log-duration-vs-client-wait)을 참조하십시오.

<Warning>
  **흔히 발생하는 오진**: 이미지가 포함된 요청에 60초의 읽기 타임아웃을 설정한 다음, 타임아웃을 서비스 중단으로 간주하고 즉시 다시 보내는 경우입니다. 실제로는 미디어가 아직 전송 중이었을 수 있습니다. 다시 보내면 동일한 페이로드를 다시 업로드하고, 동일한 업로드 대역폭을 두고 경쟁하며, 중복 태스크가 생성되어 과금될 수 있습니다.
</Warning>

## 미디어를 전달하는 세 가지 방법 비교

동일한 이미지라도 제출 시점에는 세 가지 옵션이 매우 다르게 동작합니다.

| 방법                        | 요청 본문 크기                                         | 작업 ID를 받는 시간                                          | 주요 위험                                                                |
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------- |
| **Base64 / 데이터 URL, 인라인** | 파일과 비슷한 규모이며, 인코딩으로 대략 3분의 1이 추가됩니다. 보통 수 MB입니다. | 크기와 **사용자의 업링크 대역폭**에 따라 선형적으로 증가하며, 여러 이미지에서는 누적됩니다. | 클라이언트 읽기 시간 초과가 발생할 수 있으며, 재시도할 때마다 전체 페이로드를 다시 업로드합니다.              |
| **공개 URL**                | 매우 작지만, 업스트림에서 해당 파일을 즉시 가져와야 합니다.               | **호스트가 파일을 제공하는 속도**와 파일 크기에 따라 달라집니다.                | 느리거나 요청 제한이 적용되거나, 인증이 필요하거나, 리전 간 호스트인 경우 시간이 늘어나거나 완전히 실패할 수 있습니다. |
| **`asset://` 에셋 ID**      | 수십 바이트 정도입니다.                                    | 일반적인 텍스트-동영상과 같은 수준입니다.                               | 먼저 한 번의 수집 단계가 필요합니다.                                                |

앞의 두 방법은 모델이나 추론에 의해 결정되지 않습니다. **양쪽 끝단의 대역폭과 파일 크기에 좌우되므로 둘 다 느리고 예측하기 어렵습니다.** 동일한 코드가 오늘은 8초가 걸리고 내일은 90초가 걸릴 수 있습니다. `asset://` 참조를 사용하면 이 비용을 **처음 수집 단계에서 한 번만** 부담하게 되며, 이후의 모든 생성 요청에서는 짧은 문자열만 전송합니다.

## 에셋 우선 방식은 단지 더 빠르기만 한 것이 아닙니다

<CardGroup cols={2}>
  <Card title="제출 시간이 파일 크기와 분리됩니다" icon="gauge">
    요청 본문은 prompt와 에셋 ID뿐이므로 태스크 생성 지연 시간이 텍스트-동영상 수준으로 돌아가며, 클라이언트 타임아웃은 30–60초면 충분합니다.
  </Card>

  <Card title="재시도 비용이 거의 들지 않습니다" icon="rotate-ccw">
    다른 prompt, 종횡비 또는 지속 시간으로 다시 실행할 때 수 메가바이트의 미디어를 재전송하는 대신 수십 바이트만 재전송합니다.
  </Card>

  <Card title="콘텐츠 검사가 더 일찍 수행됩니다" icon="shield-check">
    미디어는 **수집** 시점에 검증되고 `Active`까지 폴링되므로, 규정을 준수하지 않는 항목은 생성 태스크가 중간에 실패하는 대신 바로 해당 단계에서 확인됩니다.
  </Card>

  <Card title="에셋을 재사용할 수 있습니다" icon="repeat">
    한 번 수집한 후 영구적으로 재사용할 수 있습니다. 동일한 에셋 ID를 여러 샷과 에피소드에서 참조하면 캐릭터 일관성도 향상됩니다.
  </Card>
</CardGroup>

한 가지 경우에는 최적화가 아닌 **필수 요구 사항**입니다. 사실적인 사람 얼굴이 포함된 미디어는 직접 참조 이미지로 전달할 수 없으므로(딥페이크 방지), 수집한 후 `asset://`로 참조해야 합니다. [에셋 라이브러리](/ko/api-capabilities/seedance2/asset-library)를 참조하십시오.

## 세 단계로 마이그레이션

<Steps>
  <Step title="미디어를 수집하고 자산 ID를 가져옵니다">
    코드를 작성하지 않고 웹 UI를 통해 업로드하거나 API를 통해 일괄 수집할 수 있습니다. 두 경로 모두 동일한 라이브러리를 공유합니다. [자산 라이브러리](/ko/api-capabilities/seedance2/asset-library)를 참조하십시오. 상태가 `Active`이 되고 자산을 사용할 수 있을 때까지 폴링합니다(단일 이미지의 경우 약 13초).

    자산 라이브러리는 **Seedance API에서 무료이며 연회비가 없습니다**.
  </Step>

  <Step title="생성 요청에서 인라인 데이터를 asset://으로 교체합니다">
    `content` 구조, `role` 값 및 기타 모든 매개변수는 동일하게 유지됩니다. `image_url.url`의 값만 데이터 URL에서 `asset://<Id>`으로 변경됩니다. 프롬프트에서 미디어를 전달한 순서에 따라 “이미지 1”, “이미지 2”로 참조하십시오. **프롬프트 텍스트에 자산 ID를 입력하지 마십시오**.
  </Step>

  <Step title="자산 ID를 자체 데이터베이스에 저장합니다">
    자산 ID는 장기간 유지되므로 동일한 파일을 두 번 업로드하지 마십시오. 로컬 미디어와 해당 자산 ID 간의 매핑을 유지하고 이후의 모든 생성에서 이를 조회하십시오.
  </Step>
</Steps>

변경 전후의 차이는 정확히 하나의 필드 값뿐입니다.

```json 변경 전: 전체 이미지를 인라인으로 포함하며, 요청 본문은 수 MB theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in image 1 smiles at the camera, slow push-in" },
    { "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... (millions of characters)" },
      "role": "reference_image" }
  ],
  "ratio": "adaptive", "duration": 5, "resolution": "720p"
}
```

```json 변경 후: 요청 본문은 수백 바이트이며, 작업 ID가 즉시 반환됨 theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in image 1 smiles at the camera, slow push-in" },
    { "type": "image_url",
      "image_url": { "url": "asset://asset-2026090200000000-abcde" },
      "role": "reference_image" }
  ],
  "ratio": "adaptive", "duration": 5, "resolution": "720p"
}
```

업로드, 수집, 생성, 다운로드를 포함한 완전히 실행 가능한 스크립트는 [자산 참조 가이드](/ko/api-capabilities/seedance2/asset-reference)를 참조하십시오.

## 첫 프레임/마지막 프레임 작업은 어떻게 처리합니까?

첫 프레임/마지막 프레임(`role: "first_frame"` / `"last_frame"`)과 멀티모달 참조(`role: "reference_image"`)는 의미 체계가 서로 다른 **상호 배타적인 입력 모드**이므로, 아무 생각 없이 서로 바꿔 사용하지 마십시오.

* **정확한 시작 프레임과 종료 프레임이 실제로 필요한 경우** — 예를 들어 이전 클립과 끊김 없이 이어 붙여야 하는 경우 — 첫 프레임/마지막 프레임 모드를 유지하고 인라인 데이터 URL을 **공개 URL**로 교체하십시오. 요청 본문 크기가 즉시 수 메가바이트에서 수백 바이트로 줄어들며, 남은 가져오기 비용은 업스트림으로 이동합니다. 빠르고 인증이 필요 없으며 충분한 용량이 확보된 곳에 이미지를 호스팅하십시오.
* **실제로 필요한 것이 일관된 캐릭터 또는 장면인 경우** 그리고 경계 프레임이 픽셀 단위로 정확히 일치할 필요가 없다면, `asset://` 에셋 ID를 사용한 **멀티모달 참조 생성**으로 전환하십시오. 이것이 가장 안정적인 경로이며 이 페이지에서 권장하는 방식입니다.

<Tip>
  클립을 연결하여 더 긴 동영상을 만들 때 마지막 프레임을 직접 추출할 필요는 없습니다. `return_last_frame: true` 을 전달하면 다음 작업의 첫 프레임으로 사용할 워터마크 없는 마지막 프레임 png를 받습니다.
</Tip>

## 참조 동영상 및 오디오

참조 동영상(`role: "reference_video"`)은 이미지보다 훨씬 크므로 **인라인 Base64가 제출 시간 초과의 가장 유력한 원인입니다**. 다음과 같이 사용하지 않는 것이 좋습니다.

* **공개 URL을 사용하는 것이 좋습니다**. 빠르고, 인증이 필요 없으며, 충분한 리소스가 제공되는 곳에서 호스팅해야 합니다.
* 인증된 사용자용 에셋 그룹은 [에셋 라이브러리](/ko/api-capabilities/seedance2/asset-library)의 신원 확인 플로를 통해 동영상과 오디오를 수집할 수 있습니다(동영상: mp4 / mov, 2~~15초, 50MB 미만; 오디오: mp3 / wav, 2~~15초, 15MB 미만).
* 참고할 점은 다음과 같습니다. 참조 동영상이 포함된 작업에는 **더 낮은 가격 등급**이 적용됩니다. 동영상 입력이 있는 경우 토큰 100만 개당 \$7.56이며, 없는 경우에는 \$12.60입니다. [개요의 모델 가격](/ko/api-capabilities/seedance2/overview)을 참조하십시오.

## 타임아웃 후 수행할 작업

작업 생성 POST가 타임아웃되면 **클라이언트는 작업이 생성되었는지 알 수 없습니다**. 응답 헤더가 도착하지 않았으므로 조회할 작업 ID가 없습니다. 다음 순서대로 처리합니다.

<Steps>
  <Step title="무엇이든 다시 보내기 전에 기록을 확인합니다">
    APIYI 콘솔 로그 또는 과금 내역에서 해당 시점의 기록을 조회합니다. **기록이 있으면 작업이 생성되었고 과금도 완료된 것입니다** — 작업 ID가 기록에 있으므로 해당 ID를 직접 폴링합니다. 기록이 없는 경우에만 요청이 완료되지 않은 것입니다. 무조건 다시 보내면 중복 작업이 생성되고 과금됩니다.
  </Step>

  <Step title="읽기 타임아웃과 미디어 전송 방식을 함께 변경합니다">
    읽기 타임아웃만 늘리는 것은 증상만 처리하는 것입니다. `asset://`를 사용한다면 작업 생성 요청의 **30–60초** 타임아웃으로 충분합니다. 비동기 엔드포인트 자체는 빠르고 실제 작업은 작업 측에서 수행되기 때문입니다. 대용량 미디어를 계속 인라인으로 전송해야 한다면 연결 타임아웃과 읽기 타임아웃을 **별도로** 설정하고, 파일 크기와 업로드 대역폭을 기준으로 읽기 타임아웃을 정합니다.
  </Step>

  <Step title="추가로 조사하기 전에 동시 실행 수를 줄입니다">
    대용량 미디어를 포함한 여러 동시 작업 생성 요청은 동일한 업로드 회선을 공유하므로, 모든 요청이 설정한 타임아웃 값에 정확히 도달할 때 타임아웃되는 현상이 나타날 수 있습니다. 먼저 단일 요청이 정상적으로 작동하도록 한 다음 동시 실행 수를 점진적으로 늘립니다.
  </Step>

  <Step title="Base URL을 확인합니다">
    Base URL마다 서로 다른 네트워크 경로를 사용하므로 대용량 업로드의 동작도 달라질 수 있습니다. 자체 서버에서 사용 가능한 각 엔드포인트에 대한 제출 시간을 측정하고 가장 빠른 것을 사용합니다. 엔드포인트 목록과 선택 방법은 [Base URL 구성](/ko/faq/base-url-config)을 참조합니다.
  </Step>
</Steps>

일반적인 타임아웃 문제 해결 방법 — 클라이언트 타임아웃을 얼마나 길게 설정해야 하는지와 문제가 발생한 계층을 분리하는 방법 — 은 [API 타임아웃을 방지하는 방법](/ko/faq/timeout-configuration)을 참조합니다.

## FAQ

<AccordionGroup>
  <Accordion title="텍스트-투-동영상에도 에셋 라이브러리가 필요합니까?">
    아니요. 미디어가 첨부되지 않은 경우 요청 본문은 prompt뿐이며, create-task 엔드포인트는 약 1초 안에 작업 ID를 반환하므로 이 중 어느 것도 적용되지 않습니다.
  </Accordion>

  <Accordion title="ingest 자체에는 얼마나 걸립니까? 단순히 비용을 다른 곳으로 옮기는 것 아닙니까?">
    이미지 하나를 전처리하여 `Active`에 도달하는 데 약 13초가 걸립니다 — 수동 검토 없이 완전히 자동으로 처리됩니다.

    핵심은 **한 번만 처리된다는 점**입니다. 이후에는 동일한 에셋을 무기한 참조할 수 있지만, 인라인 업로드에서는 생성할 때마다 **전체 전송을 반복**합니다. 생성하는 클립이 많아질수록 그 차이는 더욱 커집니다.
  </Accordion>

  <Accordion title="에셋 ID는 만료됩니까?">
    아니요. 완성된 클립의 URL과 달리 에셋 ID는 장기간 사용할 수 있습니다. 에셋은 귀하의 icover.ai 계정에 귀속되므로 귀하의 에셋만 확인하고 사용할 수 있습니다.
  </Accordion>

  <Accordion title="에셋 라이브러리를 사용하면 추가 비용이 발생합니까?">
    아니요. Seedance API와 함께 **무료로 제공되며 연회비가 없습니다**. Volcengine 자체의 비공개 에셋 라이브러리는 프레임워크 계약이 없는 고객이 별도로 구매하는 추가 기능이며, 연간 CNY 6자리 금액의 계약이 필요합니다.
  </Accordion>

  <Accordion title="생성된 동영상 URL은 얼마나 오래 유효합니까?">
    `content.video_url`은 **24시간** 동안 유효한 서명된 직접 링크입니다. 작업이 성공하는 즉시 파일을 자체 스토리지로 복사하고, 해당 URL을 영구 주소로 배포하지 마십시오.
  </Accordion>

  <Accordion title="에셋 라이브러리 KEY는 Seedance token과 동일합니까?">
    아니요 — 두 키는 서로 다르므로 혼동하지 마십시오. **에셋 라이브러리 KEY**는 icover.ai에서 생성하며 에셋 업로드, ingest 및 조회에만 사용합니다. **APIYI Seedance 동영상 token**은 api.apiyi.com에서 생성하고 `SeeDance2` 그룹을 선택해야 하며, 동영상 생성 API에만 사용합니다.
  </Accordion>
</AccordionGroup>

## 관련 페이지

<CardGroup cols={3}>
  <Card title="에셋 라이브러리" icon="images" href="/ko/api-capabilities/seedance2/asset-library">
    모든 에셋 라이브러리 엔드포인트, 제로 코드 웹 UI 및 본인 인증
  </Card>

  <Card title="에셋 레퍼런스 가이드" icon="clapperboard" href="/ko/api-capabilities/seedance2/asset-reference">
    업로드 및 수집부터 다운로드까지 엔드투엔드 실행 가능 스크립트
  </Card>

  <Card title="Seedance 2.0 / 2.5 개요" icon="sparkles" href="/ko/api-capabilities/seedance2/overview">
    모델 선택, 과금, 해상도 표 및 FAQ
  </Card>
</CardGroup>