이미지 & 비디오 빠른 시작

이미지 & 비디오 API는 비동기 방식입니다. 생성을 제출하고 완료되면 서명된 URL에서 결과를 다운로드합니다. 이미지와 비디오는 별도의 엔드포인트를 사용하지만, 요청 및 응답 형식은 둘 다 같습니다.

결과를 수집하는 방법은 두 가지입니다. 아래 예시에서 사용하는 권장 방식은 웹훅 전송입니다. 생성이 종료 상태에 도달하는 즉시 ElevenLabs가 엔드포인트를 호출하므로 대기 시간이 소요되지 않습니다. 폴링은 콜백을 받을 엔드포인트가 없을 때의 대안이며, 각 예시에서 폴링으로 전환하는 방법도 보여줍니다.

이미지 생성

ELEVENLABS_API_KEY=<your_api_key_here>

pip install elevenlabs
pip install python-dotenv

# example.py
import os
from dotenv import load_dotenv
from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
        aspect_ratio="16:9",
        resolution="2K",
        webhook=WebhookTarget_All(),
    )
)
print(generation.id, generation.status)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}

import time
import requests
while True:
    result = elevenlabs.flows.image.get(generation.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(2)
if result.status == "failed":
    raise RuntimeError(f"{result.failure_reason}: {result.error_message}")
with open("corgi.png", "wb") as f:
    f.write(requests.get(result.content_url).content)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}

python example.py

비디오 생성

비디오 생성에는 flows.video를 사용하며 동일한 제출 및 수집 패턴을 따릅니다. 비디오는 몇 분이 걸릴 수 있으므로, 이 예시에서는 결과를 기다리는 대신 webhook을 통해 웹훅 전송을 선택합니다.

from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All
generation = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
        duration_secs=8,
        aspect_ratio="16:9",
        resolution="1080p",
        generate_audio=True,
        webhook=WebhookTarget_All(),
    )
)
print(generation.id)

생성이 대기열에 추가되면 즉시 호출이 반환되고, 완료된 결과는 생성 이벤트를 구독하는 워크스페이스의 모든 웹훅으로 전송됩니다. 비디오 출력은 MP4이므로 완료된 페이로드의 content_mime_type은 video/mp4로 보고됩니다. 웹훅 설정 및 이를 수신하는 핸들러 작성 방법은 이미지 & 비디오 웹훅을 참고하세요.

결과 수집

웹훅과 폴링은 동일한 페이로드를 반환하므로, 선택 기준은 무엇을 받는지가 아니라 결과를 기다리는 방식입니다.

가능한 경우 웹훅을 사용하세요. 콜백을 받을 곳이 없을 때는 폴링을 사용하고, 폴링할 경우 아래 간격을 따르세요.

웹훅 대상 선택

webhook은 두 가지 형식을 허용합니다. WebhookTarget_All은 생성 이벤트를 구독하는 모든 웹훅에 전송하며, 웹훅이 교체되거나 순환되어도 유지되므로 적절한 기본값입니다. WebhookTarget_Ids는 전송 대상을 특정 웹훅으로 제한합니다. 하나의 워크스페이스가 여러 소비자에게 분배하고 특정 작업이 그중 하나에만 전달되어야 할 때 사용합니다.

from elevenlabs import WebhookTarget_Ids
webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])

모든 ID는 이미 생성 이벤트를 구독하고 있어야 합니다. 구독하지 않은 웹훅을 지정하면 조용히 무시되지 않고 거부됩니다. 전송되는 페이로드는 GET 엔드포인트가 반환하는 내용과 동일하므로, 한쪽에 맞춰 작성한 핸들러는 다른 쪽에서도 작동합니다. 웹훅 가이드에서는 웹훅 설정, 서명 검증 및 이벤트 처리 방법을 다룹니다.

폴링 가이드라인

생성 실행 시간은 모델, 해상도, 그리고 비디오의 경우 길이에 따라 달라집니다. 고정 루프를 사용하는 대신 요청한 조건에 맞는 간격으로 폴링하세요.

• 이미지: 2초에 한 번보다 자주 폴링하지 마세요. 대부분 몇 초 안에 완료됩니다.
• 비디오: 10초에 한 번보다 자주 폴링하지 마세요. 몇 초가 아닌 몇 분을 예상하고, duration_secs 및 resolution에 따라 간격을 조정하세요.

두 방식 모두에 두 가지 규칙이 적용됩니다. 생성이 오래 걸리면 백오프하세요. 간격을 약 1분까지 두 배로 늘리면 느린 생성이 수백 건의 요청으로 이어지는 것을 방지할 수 있습니다. 또한 자체 코드에서 멈춘 생성이 제한 없는 루프가 아니라 타임아웃으로 종료되도록 루프에 상한을 두세요.

이보다 빠르게 폴링해도 이점이 없습니다. 두 번 요청한다고 생성 상태가 더 빨리 바뀌지는 않습니다. 지속적으로 과도한 폴링을 하면 429 응답이 반환될 수 있으므로 지수 백오프로 처리해야 합니다.

생성 수명 주기

생성은 네 가지 상태를 거칩니다. 두 종료 상태는 서로 다른 필드를 포함하므로, 나머지 응답을 읽기 전에 status를 기준으로 분기하세요.

실패 처리

실패한 생성은 사람이 읽을 수 있는 error_message와 함께 failure_reason 카테고리를 보고합니다.

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}

실패한 생성에는 비용이 청구되지 않습니다. 지원되지 않는 필드, 모델에서 허용하는 범위를 벗어난 값, 잘못된 참조 입력 조합처럼 사전에 감지할 수 있는 파라미터 문제는 생성이 시작되기 전에 생성 요청에서 거부됩니다.

가격

생성에는 크레딧이 청구됩니다. 비용은 모델, 해상도 및 길이 같은 선택한 파라미터, 제공한 입력에 따라 달라집니다. 생성 비용은 API와 ElevenLabs 앱에서 동일하며, 앱에서는 제출 전에 비용이 표시됩니다. 특정 모델 및 설정 조합의 비용이 표시되는 방법은 플레이그라운드의 이미지 & 비디오를 참고하세요.

생성 목록 보기

각 엔드포인트는 해당 엔드포인트를 통해 생성된 항목을 최신순으로 나열합니다. 결과는 워크스페이스와 이 API로 범위가 제한되므로 ElevenLabs 앱에서 생성한 항목은 표시되지 않습니다.

page = elevenlabs.flows.image.list(page_size=20, status="completed")
for item in page.generations:
    print(item.id, item.content_url)
while page.has_more:
    page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor)
    for item in page.generations:
        print(item.id, item.content_url)

page_size는 1~100을 허용하며 기본값은 30입니다. 하나의 수명 주기 상태에 있는 생성만 반환하려면 status를 전달하고, 단일 모델의 생성만 반환하려면 model_id를 전달하세요. next_cursor는 불투명한 값으로 취급하세요. 정확한 값을 그대로 다시 전달하고 has_more가 false이면 중지하세요.

사용 가능한 모델

API는 ElevenLabs 앱에서 사용할 수 있는 모델 중 일부를 제공합니다. 각 모델은 해당 모델에 나열된 매개변수만 허용합니다. 다른 모델에서 지원하는 필드를 전송하면 유효성 검사 오류가 반환됩니다.

이미지 모델

GPT Image 2.5 모델은 low, medium, high, xhigh, max의 quality 값을 지원하며, 기본값은 high입니다. GPT Image 2는 high까지만 지원하며 기본값은 medium입니다.

비디오 모델

모델 기능, 사용 가능 여부 및 가격은 이미지 & 비디오 개요에서 확인하세요.

다음 단계