참조 및 에셋

개요

대부분의 이미지 & 비디오 모델은 프롬프트와 함께 미디어를 허용합니다. 비디오의 첫 프레임, 편집할 이미지, 립싱크에 사용할 오디오 등이 이에 해당합니다. API의 모든 미디어 값 필드는 고정된 형식의 원시 바이트가 아닌 참조 객체를 사용하며, 각 참조에는 미디어 출처를 나타내는 type이 태그로 지정됩니다.

세 가지 유형은 참조를 허용하는 모든 곳에서 서로 바꿔 사용할 수 있으므로, 동일한 필드에 한 요청에서는 생성을, 다음 요청에서는 업로드한 에셋을 사용할 수 있습니다.

한 생성 결과를 다음 생성에 연결하기

generation 참조는 완료된 생성만 가리킬 필요가 없습니다. 이미지를 제출하고 응답에서 ID를 가져와 기다리지 않고 바로 비디오 요청에 전달하세요. API가 이미지 뒤에 비디오를 대기열에 넣고 이미지가 완료되는 즉시 시작합니다. 두 호출 사이에 업로드할 작업은 없습니다.

체인의 마지막 생성에 webhook을 설정하면 전혀 기다릴 필요가 없습니다. 두 호출은 생성이 대기열에 추가되는 즉시 반환되고, 전체 그래프는 서버 측에서 실행되며, 마지막 생성이 종료 상태에 도달하면 엔드포인트가 호출됩니다.

from elevenlabs import (
    ImageGenerationRequest_Gemini3ProImage,
    ImageReference_Generation,
    VideoGenerationRequest_Veo31FastGenerate001,
    WebhookTarget_All,
)
still = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
        aspect_ratio="16:9",
    )
)
# `still` is still pending here. Submitting now queues the video behind it.
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The fog thickens and the beam sweeps across the water",
        start_frame=ImageReference_Generation(generation_id=still.id),
        duration_secs=8,
        webhook=WebhookTarget_All(),
    )
)
print(clip.id)

webhook은 마지막 생성에만 필요합니다. 이미지에도 설정하면 중간 결과에 대한 이벤트도 전달되므로 진행 상황을 보고하는 데 유용하지만 체인을 실행하는 데 필요하지는 않습니다. 다른 곳과 마찬가지로 이 필드에는 생성 이벤트를 구독하는 웹훅이 필요합니다. 설정 방법은 이미지 & 비디오 웹훅을 참조하세요.

콜백을 수신할 엔드포인트가 없다면 webhook을 제거하고 대신 체인의 마지막을 폴링하세요. 중간 이미지는 여전히 별도로 폴링할 필요가 없습니다. 마지막 생성에 대해 해당 모달리티의 간격으로 한 번만 기다리면 됩니다. 비디오의 경우 10초에 한 번을 넘지 않아야 합니다. 폴링 가이드라인을 참조하세요.

import time
while True:
    result = elevenlabs.flows.video.get(clip.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(10)

완료되지 않은 작업을 참조하는 생성은 즉시 생성되며, 참조하는 모든 작업이 완료될 때까지 pending 상태로 대기합니다. 시작을 위해 추가로 수행할 작업은 없습니다. 체인은 깊이와 너비에 제한이 없습니다. 하나의 생성이 여러 참조를 기다릴 수 있고, 각각의 참조도 계속 대기 중일 수 있으므로 전체 그래프를 한 번에 제출하고 리프에서만 수집할 수 있습니다. 대기열에서 보낸 시간은 생성의 타임아웃에 포함되지 않습니다.

참조된 생성이 실패하면 종속 생성은 실행되지 않습니다. dependency_failed 사유로 실패하며, 그 뒤에 대기 중인 모든 작업도 함께 실패합니다. 중단된 체인의 어떤 작업에도 요금이 청구되지 않습니다. 이미 비용을 지불한 생성은 환불되며, 대기 중인 오디오 생성의 길이를 기준으로 가격이 책정되는 립싱크처럼 아직 존재하지 않는 참조 출력에 따라 가격이 결정되는 생성은 시작될 때만 청구됩니다. 워크스페이스에 존재하지 않는 generation_id는 생성 호출 자체에서 거부되므로, 오타는 실패한 생성이 아니라 즉시 오류로 표시됩니다.

미디어를 에셋으로 업로드하기

미디어가 ElevenLabs 외부에서 오고 여러 생성에서 재사용하려면 파일을 에셋 API에 업로드하세요. 에셋은 워크스페이스에 속하며 삭제할 때까지 유지됩니다.

from elevenlabs import ImageReference_Asset, VideoGenerationRequest_Veo31FastGenerate001
with open("lighthouse.png", "rb") as f:
    asset = elevenlabs.assets.create(asset=f, name="lighthouse.png")
print(asset.asset_id)
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The beam sweeps across the water as the fog thickens",
        start_frame=ImageReference_Asset(asset_id=asset.asset_id),
    )
)

업로드 응답은 저장된 에셋을 설명합니다.

{
  "asset_id": "5xM2KqOnZyce22SPZ9d4",
  "name": "lighthouse.png",
  "mime_type": "image/png",
  "created_at_unix": 1721520000,
  "content_url": "https://storage.googleapis.com/assets/5xM2KqOnZyce22SPZ9d4"
}

content_url은 약 1시간 동안 유효한 서명된 URL이며, 업로드가 아직 처리 중인 동안에는 null입니다. 새 URL이 필요하면 에셋을 다시 가져오세요.

저장 공간 제한

업로드한 에셋은 워크스페이스의 총 저장 공간 제한에 포함되며, 제한은 요금제에 따라 다릅니다.

생성된 출력은 포함되지 않고 업로드한 파일만 제한에 포함됩니다. 워크스페이스가 제한을 초과하게 되는 업로드는 파일을 읽기 전에 asset_storage_limit_exceeded 오류와 함께 거부됩니다. 더 이상 필요하지 않은 에셋을 삭제하여 공간을 확보하거나, 지원팀에 문의해 제한 상향을 요청하세요.

에셋 관리

에셋을 최신순으로 나열하고, 필요에 따라 이름으로 필터링하며, 이전 응답의 커서로 결과를 페이지 단위로 확인하세요. page_size는 1~100을 허용하며 기본값은 30입니다.

page = elevenlabs.assets.list(page_size=20, search="lighthouse")
for asset in page.assets:
    print(asset.asset_id, asset.name, asset.mime_type)
if page.has_more:
    page = elevenlabs.assets.list(page_size=20, search="lighthouse", cursor=page.next_cursor)

ID로 단일 에셋을 가져오거나 삭제할 수 있습니다. 에셋을 삭제해도 이미 해당 에셋을 사용한 생성에는 영향을 주지 않습니다.

asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4")
elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4")

미디어를 인라인으로 전달하기

inline_base64 참조는 요청 본문에 미디어를 담으므로 일회성 입력을 위해 별도로 업로드할 필요가 없습니다. 표준 base64 알파벳으로 파일을 인코딩하고 MIME 유형을 지정하세요.

import base64
from elevenlabs import ImageGenerationRequest_GptImage2, ImageReference_InlineBase64
with open("headshot.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_GptImage2(
        prompt="Replace the background with a softly lit studio backdrop",
        images=[
            ImageReference_InlineBase64(
                content_base64=encoded,
                mime_type="image/jpeg",
            )
        ],
    )
)

인라인 콘텐츠는 디코딩 후 참조당 25MB로 제한됩니다. 더 큰 파일은 훨씬 큰 업로드를 허용하고 base64 크기 패널티가 없는 에셋 API를 사용해야 합니다. 각 모달리티는 정해진 MIME 유형 집합을 허용합니다.

모델별 참조 필드

참조 필드는 미디어가 수행하는 역할에 따라 이름이 지정됩니다. start_frame과 end_frame은 비디오의 범위를 정하는 단일 이미지이고, image와 audio는 립싱크 모델의 필수 입력이며, 복수형인 images, videos, audios는 모델이 활용하는 자유 형식의 참조 자료입니다.

모델마다 허용하는 필드와 유효한 조합이 다릅니다. end_frame에는 항상 start_frame이 필요합니다. 제약 조건을 위반하면 문제가 있는 필드를 지정한 유효성 검사 오류가 반환되므로 생성이 시작되지 않으며 비용도 청구되지 않습니다.

Veo 3.1

두 Veo 모델은 start_frame, end_frame, 그리고 images에 최대 3개의 항목을 허용합니다. 다른 모델과 달리 images의 각 항목은 참조와 그 역할을 함께 감쌉니다.

{
  "images": [
    {
      "image": { "type": "asset", "asset_id": "5xM2KqOnZyce22SPZ9d4" },
      "role": "subject"
    },
    {
      "image": { "type": "asset", "asset_id": "7pQ4LnBvXkR2mT9wYcHd" },
      "role": "style"
    }
  ]
}

subject 참조는 이미지의 피사체 또는 장면 요소를 비디오에 배치하고, style 참조는 시각적 스타일을 전달합니다. 참조 이미지는 start_frame 또는 end_frame과 함께 사용할 수 없으며, 8초 길이가 필요합니다.

Seedance

세 가지 Seedance 2.0 등급은 start_frame, end_frame, 최대 9개의 images, 최대 3개의 videos, 최대 3개의 audios를 허용하며, 다음 제약 조건이 적용됩니다.

• 참조는 start_frame 또는 end_frame과 함께 사용할 수 없습니다.
• 참조 오디오는 예를 들어 립싱크를 구동하기 위해 하나 이상의 참조 이미지 또는 비디오가 필요합니다.
• 참조 파일의 총수는 12개를 초과할 수 없습니다.

Seedance 2.5는 제한을 총합 제한 없이 images 30개, videos 10개, audios 10개로 늘리고, 참조 오디오에 함께 사용할 이미지 또는 비디오가 필요하다는 규칙을 없앴습니다. 따라서 오디오 전용 입력도 허용됩니다. 참조는 여전히 start_frame 또는 end_frame과 함께 사용할 수 없습니다.

GPT Image

GPT Image 모델은 images와 함께 mask를 허용합니다. 마스크의 완전히 투명한 영역은 첫 번째 참조 이미지에서 편집할 수 있는 위치를 표시합니다. 참조 이미지가 없는 마스크는 거부됩니다.

다음 단계