参考内容和资源

概览

大多数图像和视频模型都接受提示词以外的媒体：视频的首帧、用于编辑的图像、用于口型同步的音频。API 中每个媒体字段都接受固定结构的引用对象，而非原始字节；每个引用均带有 type，用于说明媒体来源。

在所有接受引用的位置，这 3 种类型均可互换。因此，同一字段可在一个请求中接受生成内容，在下一个请求中接受上传的资源。

将一次生成串联到下一次

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 订阅生成事件；设置方法请参阅图像和视频 Webhooks。

如果没有接收回调的端点，请移除 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。更大的文件应上传到资源 API，它接受更大的上传内容，且不会产生 base64 的大小损耗。每种媒体类型均接受固定的一组 MIME 类型：

按模型查看引用字段

引用字段以媒体的用途命名。start_frame 和 end_frame 是界定视频的单张图像，image 和 audio 是口型同步模型的必填输入，而复数形式的 images、videos 和 audios 则是模型可自由参考的素材。

每个模型接受哪些字段、哪些组合有效均不相同。end_frame 始终需要 start_frame。违反约束会返回指明问题字段的验证错误，因此生成不会启动，也不会收费。

Veo 3.1

两种 Veo 模型均接受 start_frame、end_frame，以及最多 3 个 images 条目。与其他模型不同，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

3 个 Seedance 2.0 版本均接受 start_frame、end_frame、最多 9 个 images、最多 3 个 videos 和最多 3 个 audios，但需遵守以下限制：

• 引用不能与 start_frame 或 end_frame 结合使用。
• 参考音频至少需要一个参考图像或视频，例如用于驱动口型同步。
• 参考文件总数不得超过 12 个。

Seedance 2.5 将上限提高至 30 个 images、10 个 videos 和 10 个 audios，且不设总数限制；同时取消了参考音频需要搭配图像或视频的规则，因此接受仅音频输入。引用仍不能与 start_frame 或 end_frame 结合使用。

GPT Image

GPT Image 模型接受与 images 一同传入的 mask。遮罩中完全透明的区域标记首张参考图像可编辑的位置。不带参考图像的遮罩会被拒绝。

后续步骤