图像和视频快速入门

图像和视频 API 是异步的。提交生成任务后，完成时可通过签名 URL 下载结果。图像和视频使用不同的端点，但请求和响应结构相同。

有两种方式获取结果。推荐使用Webhook 推送，下方示例也采用此方式：生成任务进入终止状态后，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 启用 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)

生成任务进入队列后，调用便会返回；完成的结果会推送到工作区中订阅了生成事件的每个 Webhook。视频输出为 MP4，因此完成后的载荷中 content_mime_type 为 video/mp4。请参阅图像和视频 Webhook，了解如何配置 Webhook 并编写接收此结果的处理程序。

获取结果

Webhook 和轮询返回相同的载荷，因此区别在于等待方式，而非获取的内容。

尽可能使用 Webhook。仅在没有可接收回调的位置时使用轮询，并遵循以下间隔。

选择 Webhook 目标

webhook 支持两种形式。WebhookTarget_All 会发送到订阅生成事件的所有 Webhook，这是正确的默认选择，因为即使 Webhook 轮换或替换，仍可正常工作。WebhookTarget_Ids 会将推送范围限定为特定 Webhook，适用于一个工作区服务多个消费者，而某个任务只应发送给其中一个的情况：

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

每个 ID 都必须已订阅生成事件；指定未订阅的 Webhook 会被拒绝，而不会被静默忽略。推送的载荷与 GET 端点返回的内容相同，因此针对其中一种编写的处理程序可用于另一种。Webhook 指南介绍了如何配置 Webhook、验证签名和处理事件。

轮询指南

生成任务的耗时取决于模型、分辨率，以及视频时长。因此，应根据请求内容匹配轮询间隔，而非固定循环：

• 图像：轮询间隔不得少于 2 秒。大多数会在数秒内完成。
• 视频：轮询间隔不得少于 10 秒。预计耗时为数分钟而非数秒，并应根据 duration_secs 和 resolution 调整间隔。

两者均适用以下两条规则。生成任务长时间运行时应退避——将间隔逐步加倍至约 1 分钟，可避免缓慢任务产生数百个请求。同时，为循环设置上限，让卡住的生成任务在你的代码中以超时结束，而不是无限循环。

更频繁的轮询没有任何收益：不会因为请求两次，生成任务的状态就更早变化。持续激进轮询可能返回429 响应，应使用指数退避处理。

生成生命周期

生成任务会经历 4 种状态。两种终止状态包含不同字段，因此读取响应其余内容前，请先根据 status 分支处理。

处理失败

失败的生成任务会报告 failure_reason 类别，以及便于阅读的 error_message：

{
  "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 应用中相同，提交前会显示费用。请参阅Playground 中的图像和视频，了解如何显示特定模型和设置组合的费用。

列出生成任务

每个端点都会列出通过其创建的生成任务，按最新优先排序。结果仅限当前工作区和此 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。

视频模型

有关模型能力、可用性和定价，请参阅图像和视频概览。

后续步骤