> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 参考内容和资源

> **Note**
>
> **操作指南** · 假设你已完成[图像和视频快速入门](/docs/zh/eleven-api/guides/cookbooks/image-and-video)。

## 概览

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

| `type`          | 指向                    | 字段                           |
| --------------- | --------------------- | ---------------------------- |
| `generation`    | 另一项生成的输出，无论已完成还是仍在运行。 | `generation_id`              |
| `asset`         | 上传到资源 API 的文件。        | `asset_id`                   |
| `inline_base64` | 直接编码在请求正文中的媒体。        | `content_base64`、`mime_type` |

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

## 将一次生成串联到下一次

`generation` 引用不必指向已完成的生成。提交图像后，从响应中获取 ID，直接传入视频请求，无需等待：API 会将视频排在图像之后，并在图像完成后立即开始。两次调用之间无需上传任何内容。

在链中的最后一次生成上设置 `webhook`，便完全无需等待。两个调用都会在生成排队后立即返回，整个图会在服务器端运行，最终生成达到终态后会调用你的端点。

```python maxLines=0
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)
```

```typescript maxLines=0
const still = await elevenlabs.flows.image.create({
  modelId: "gemini-3-pro-image",
  prompt: "A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
  aspectRatio: "16:9",
});

// `still` is still pending here. Submitting now queues the video behind it.
const clip = await elevenlabs.flows.video.create({
  modelId: "veo-3.1-fast-generate-001",
  prompt: "The fog thickens and the beam sweeps across the water",
  startFrame: { type: "generation", generationId: still.id },
  durationSecs: 8,
  webhook: { type: "all" },
});

console.log(clip.id);
```

只有最后一次生成需要 `webhook`。同时在图像上设置它，也会为中间结果发送事件，这有助于报告进度，但并非驱动该链所必需。与其他情况一样，此字段要求 webhook 订阅生成事件；设置方法请参阅[图像和视频 Webhooks](/docs/zh/eleven-api/guides/how-to/image-and-video/webhooks)。

如果没有接收回调的端点，请移除 `webhook`，改为轮询链的末端。中间图像仍无需单独轮询——只需在最后一次生成上等待一次，并按其媒体类型的间隔轮询；对于视频，频率最多每 10 秒一次。请参阅[轮询指南](/docs/zh/eleven-api/guides/cookbooks/image-and-video#polling-guidelines)。

```python
import time

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

```typescript
let result = await elevenlabs.flows.video.get(clip.id);
while (result.status === "pending" || result.status === "generating") {
  await new Promise((resolve) => setTimeout(resolve, 10000));
  result = await elevenlabs.flows.video.get(clip.id);
}
```

引用未完成任务的生成会立即创建，并保持 `pending` 状态，直到其引用的所有内容完成；无需采取其他操作即可启动。链可以有任意深度和宽度——一次生成可等待多个引用，而每个引用本身也仍在等待——因此可一次提交整个图，仅在其叶节点收集结果。排队时间不计入生成的超时时间。

如果被引用的生成失败，依赖它的生成不会运行：它会因 `dependency_failed` 原因失败，并连带使其后排队的内容失败。已中断链中的所有内容均不会收费——已付费的生成会退款；价格依赖尚不存在的引用输出的生成，例如按待处理音频生成时长计费的口型同步，则仅会在开始后收费。工作区中不存在的 `generation_id` 会在创建调用时被拒绝，因此拼写错误会立即显示，而不会表现为生成失败。

## 将媒体上传为资源

当媒体来自 ElevenLabs 外部，且希望跨多个生成重复使用时，请将文件上传到资源 API。资源属于工作区，会一直保留到你删除它们为止。

```python
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),
    )
)
```

```typescript
import { createReadStream } from "fs";

const asset = await elevenlabs.assets.create({
  asset: createReadStream("lighthouse.png"),
  name: "lighthouse.png",
});

console.log(asset.assetId);

const clip = await elevenlabs.flows.video.create({
  modelId: "veo-3.1-fast-generate-001",
  prompt: "The beam sweeps across the water as the fog thickens",
  startFrame: { type: "asset", assetId: asset.assetId },
});
```

上传响应会描述已存储的资源：

```json
{
  "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。

> **Warning**
>
> 使用 API 密钥访问资源 API 需要 Pro 或更高版本，与生成端点要求的套餐级别相同。

### 存储限制

上传的资源会计入工作区总存储限制，具体取决于套餐：

| 套餐         | 资源存储空间 |
| ---------- | ------ |
| Pro        | 11 GB  |
| Scale      | 33 GB  |
| Business   | 111 GB |
| Enterprise | 333 GB |

只有上传的文件会计入限制，生成的输出不会。会导致工作区超出限制的上传会在读取文件前被拒绝，并返回 `asset_storage_limit_exceeded` 错误。删除不再需要的资源以释放空间，或联系支持团队提高限制。

### 管理资源

按最新优先列出资源，可选择按名称筛选，并使用上一个响应中的游标分页。`page_size` 接受 1 至 100，默认值为 30。

```python
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)
```

```typescript
let page = await elevenlabs.assets.list({ pageSize: 20, search: "lighthouse" });

for (const asset of page.assets) {
  console.log(asset.assetId, asset.name, asset.mimeType);
}

if (page.hasMore) {
  page = await elevenlabs.assets.list({
    pageSize: 20,
    search: "lighthouse",
    cursor: page.nextCursor,
  });
}
```

可通过 ID 获取或删除单个资源。删除资源不会影响已使用它的生成。

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

```typescript
const asset = await elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4");
await elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4");
```

## 内联传递媒体

`inline_base64` 引用会在请求正文中携带媒体，避免为一次性输入单独上传。使用标准 base64 字母表编码文件，并声明其 MIME 类型。

```python
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",
            )
        ],
    )
)
```

```typescript
import { readFile } from "fs/promises";

const encoded = (await readFile("headshot.jpg")).toString("base64");

const generation = await elevenlabs.flows.image.create({
  modelId: "gpt-image-2",
  prompt: "Replace the background with a softly lit studio backdrop",
  images: [
    {
      type: "inline_base64",
      contentBase64: encoded,
      mimeType: "image/jpeg",
    },
  ],
});
```

> **Warning**
>
> 内联媒体会作为临时资源存储，不保证保留，生成完成后可能被删除。如需多次引用同一输入，请改为将文件上传到资源 API。

解码后，每个引用的内联内容上限为 25MB。更大的文件应上传到资源 API，它接受更大的上传内容，且不会产生 base64 的大小损耗。每种媒体类型均接受固定的一组 MIME 类型：

| 引用 | 接受的 `mime_type`                                                 |
| -- | --------------------------------------------------------------- |
| 图像 | `image/jpeg`、`image/png`、`image/webp`、`image/heic`、`image/heif` |
| 音频 | `audio/mpeg`、`audio/wav`                                        |
| 视频 | `video/mp4`、`video/quicktime`、`video/webm`                      |

## 按模型查看引用字段

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

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

### Veo 3.1

两种 Veo 模型均接受 `start_frame`、`end_frame`，以及最多 3 个 `images` 条目。与其他模型不同，`images` 中每个条目都会将引用与其所发挥的角色封装在一起：

```json
{
  "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

> **Warning**
>
> ByteDance 模型默认禁用，使用前需获得明确批准。企业版客户可联系支持团队申请访问权限。

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`。遮罩中完全透明的区域标记首张参考图像可编辑的位置。不带参考图像的遮罩会被拒绝。

## 后续步骤

#### [Webhooks](/docs/zh/eleven-api/guides/how-to/image-and-video/webhooks)

接收生成结果，无需轮询。

#### [图像和视频概览](/docs/zh/overview/capabilities/image-video)

比较模型功能、支持的格式和可用性。

#### [API 参考文档](/docs/zh/api-reference/flows/image/create)

查看图像、视频和资源端点。