# LTX-2.5 Pro — Scenepond API

模型 ID: `lightricks/ltx-2.5/image-to-video/pro`

模型开发者: Lightricks

用途: 图生视频

原始页面: https://open.scenepond.ai/zh/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Fpro#api

核对日期: 2026-10-01

API 地址: `https://scenepond-api-production.up.railway.app/v1`

每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。

## 原生任务 API

`POST /v1/tasks/fal`

### 最小调用

#### cURL

```bash
curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/tasks/fal" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "image_url": "https://example.com/reference.png",
  "prompt": "A quiet lakeside at sunrise"
}
JSON
```

#### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

payload = json.loads("{\n  \"model\": \"lightricks/ltx-2.5/image-to-video/pro\",\n  \"image_url\": \"https://example.com/reference.png\",\n  \"prompt\": \"A quiet lakeside at sunrise\"\n}")

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/fal",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

#### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/fal", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "image_url": "https://example.com/reference.png",
  "prompt": "A quiet lakeside at sunrise"
})
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 请求参数

- `model` — **必填**; `string`. 使用此处显示的完整公开模型 ID。
  - 约束: `const = "lightricks/ltx-2.5/image-to-video/pro"`

- `camera_motion` — **可选**; `string`. 期望的镜头运动预设。
  - 约束: `enum = ["dolly_in","dolly_out","dolly_left","dolly_right","jib_up","jib_down","static","focus_shift"]`

- `resolution` — **可选**; `string`. 输出分辨率。允许值取决于此模型，并区分大小写。
  - 默认: `"1080p"`
  - 约束: `enum = ["720p","1080p"]`

- `image_url` — **条件必填**; `string`. 参考图片；提供可访问的 HTTP(S) 地址或 base64 图片 data URL。
  - 未通过 images、image 或 input_reference 提供参考图片时必填。

- `duration` — **可选**; `integer`. 请求的视频时长，单位为秒。
  - 默认: `8`
  - 约束: `enum = [6,8,10]`

- `aspect_ratio` — **可选**; `string`. 期望的输出宽高比。
  - 默认: `"auto"`
  - 约束: `enum = ["auto","16:9","9:16"]`

- `generate_audio` — **可选**; `boolean`. 是否请求生成音频。
  - 默认: `true`

- `prompt` — **必填**; `string`. 描述主体、场景和期望生成的内容。
  - 约束: `maxLength = 5000`; `minLength = 1`

- `end_image_url` — **可选**; `string`. 可选尾帧图片；同时需要提供起始参考图片。

- `fps` — **可选**; `integer`. 期望的每秒帧数。
  - 默认: `25`
  - 约束: `enum = [24,25,50]`

- `seconds` — **可选**; `integer`. 视频时长，单位为秒；此字段是 duration 的别名。
  - 默认: `8`
  - 约束: `enum = [6,8,10]`

- `size` — **可选**; `string`. image_size 或 resolution 的别名。建议使用本表准确的原生值；像素尺寸别名可能不匹配区分大小写的分辨率值。

- `parameters` — **可选**; `object`. 本表原生参数的另一种容器写法；同一设置不可重复填写不同值。

- `metadata` — **可选**; `object`. 另一种容器写法：将原生参数放在 metadata.parameters 内。

- `images` — **可选**; `array<string>`. 可代替原生参考图片字段。第一项作为起始图片；仅在模型支持尾帧时才能提供第二项。
  - 约束: `maxItems = 2`

- `image` — **可选**; `string | array<string>`. 参考图片的另一种别名写法，不可与原生图片字段或 input_reference 同时使用。

- `input_reference` — **可选**; `string | array<string>`. 参考图片的另一种别名写法，不可与原生图片字段或 image 同时使用。

### 响应示例

响应示例仅展示结构；ID、URL 和数值为占位内容。

#### 提交响应

```json
{
  "id": "task_EXAMPLE",
  "task_id": "task_EXAMPLE",
  "status": "queued",
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "created_at": 1700000000
}
```

#### 已完成任务的状态

```json
{
  "task_id": "task_EXAMPLE",
  "platform": "fal",
  "status": "SUCCESS",
  "progress": "100%",
  "fail_reason": "",
  "created_at": 1700000000,
  "finished_at": 1700000060
}
```

#### 生成文件列表

```json
{
  "task_id": "task_EXAMPLE",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://scenepond-api-production.up.railway.app/v1/tasks/task_EXAMPLE/artifacts/video/content"
    }
  ]
}
```

### 后续请求

#### 2. 查询任务状态

将 SCENEPOND_TASK_ID 设为返回的 task_id，每隔几秒查询，直到 SUCCESS 或 FAILURE。状态中包含进度和 fail_reason，但不包含生成文件。

##### cURL

```bash
curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

#### 3. 获取生成结果

SUCCESS 后查询生成文件列表，使用返回的 content_url 和认证信息下载。请妥善保管带签名的地址。

##### cURL

```bash
curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID/artifacts" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "/artifacts",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "/artifacts", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 调用注意事项

- 每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。
- 参数值区分大小写。未填写或为 null 时，存在默认值的设置使用默认值；有效的 0 和 false 会被保留。
- 参数表使用 JSON 顶层的原生字段名，也可放入 parameters 或 metadata.parameters。未知的嵌套字段和重复参数中的冲突值会被拒绝。
- 提交后返回排队任务。先轮询状态，再在 SUCCESS 后查询生成文件列表。
- POST 超时后不要自动重新提交。保存已返回的任务 ID，先检查状态，再决定是否创建新的付费任务。
- 默认值和限制依据当前网关与关联的上游参数规范；上游或网关更新后可能变化。
- 将 example.com 替换为自己可访问的参考图片地址。原生图片字段与 images/input_reference 别名选一种写法，不能重复提供。
- 提供尾帧时必须同时提供起始参考图片，不能只提交尾帧。

## Video API

`POST /v1/videos`

### 最小调用

#### cURL

```bash
curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/videos" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "prompt": "A quiet lakeside at sunrise",
  "input_reference": "https://example.com/reference.png"
}
JSON
```

#### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

payload = json.loads("{\n  \"model\": \"lightricks/ltx-2.5/image-to-video/pro\",\n  \"prompt\": \"A quiet lakeside at sunrise\",\n  \"input_reference\": \"https://example.com/reference.png\"\n}")

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/videos",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

#### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/videos", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "prompt": "A quiet lakeside at sunrise",
  "input_reference": "https://example.com/reference.png"
})
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 请求参数

- `model` — **必填**; `string`. 使用此处显示的完整公开模型 ID。
  - 约束: `const = "lightricks/ltx-2.5/image-to-video/pro"`

- `prompt` — **必填**; `string`. 描述主体、场景和期望生成的内容。
  - 约束: `maxLength = 5000`; `minLength = 1`

- `input_reference` — **条件必填**; `string`. 参考图片；提供可访问的 HTTP(S) 地址或 base64 图片 data URL。
  - 未通过原生参考图片字段或 images 提供参考图片时必填。

- `seconds` — **可选**; `integer`. 视频时长，单位为秒；此字段是 duration 的别名。
  - 默认: `8`
  - 约束: `enum = [6,8,10]`

- `metadata` — **可选**; `object`. 模型生成设置的可选容器。

### metadata 中的字段

仅在提供 metadata 时适用；子字段必填不代表可选的父字段也必填。

- `metadata.parameters` — **可选**; `object`. 仅接受下方列出的模型设置。

### metadata.parameters 中的字段

仅在提供 metadata.parameters 时适用；子字段必填不代表可选的父字段也必填。

- `metadata.parameters.camera_motion` — **可选**; `string`. 期望的镜头运动预设。
  - 约束: `enum = ["dolly_in","dolly_out","dolly_left","dolly_right","jib_up","jib_down","static","focus_shift"]`

- `metadata.parameters.resolution` — **可选**; `string`. 输出分辨率。允许值取决于此模型，并区分大小写。
  - 默认: `"1080p"`
  - 约束: `enum = ["720p","1080p"]`

- `metadata.parameters.duration` — **可选**; `integer`. 请求的视频时长，单位为秒。
  - 默认: `8`
  - 约束: `enum = [6,8,10]`

- `metadata.parameters.aspect_ratio` — **可选**; `string`. 期望的输出宽高比。
  - 默认: `"auto"`
  - 约束: `enum = ["auto","16:9","9:16"]`

- `metadata.parameters.generate_audio` — **可选**; `boolean`. 是否请求生成音频。
  - 默认: `true`

- `metadata.parameters.end_image_url` — **可选**; `string`. 可选尾帧图片；同时需要提供起始参考图片。

- `metadata.parameters.fps` — **可选**; `integer`. 期望的每秒帧数。
  - 默认: `25`
  - 约束: `enum = [24,25,50]`



- `parameters` — **可选**; `object`. 本表原生参数的另一种容器写法；同一设置不可重复填写不同值。

### 响应示例

响应示例仅展示结构；ID、URL 和数值为占位内容。

#### 视频响应

```json
{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1700000000
}
```

### 后续请求

#### 查询视频状态

将 SCENEPOND_TASK_ID 设为返回的视频 id，轮询至 completed 或 failed。

##### cURL

```bash
curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/videos/$SCENEPOND_TASK_ID" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/videos/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/videos/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

#### 下载视频

completed 后将文件下载到 output.bin；Content-Type 响应头表示文件格式。

##### cURL

```bash
curl --fail-with-body --output output.bin -X GET "https://scenepond-api-production.up.railway.app/v1/videos/$SCENEPOND_TASK_ID/content" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/videos/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "/content",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    with open("output.bin", "wb") as output:
        output.write(response.read())
print("Saved output.bin")
```

##### JavaScript

```javascript
import { writeFile } from "node:fs/promises";
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/videos/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "/content", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
await writeFile("output.bin", Buffer.from(await response.arrayBuffer()));
console.log("Saved output.bin");
```

### 调用注意事项

- 每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。
- 参数值区分大小写。未填写或为 null 时，存在默认值的设置使用默认值；有效的 0 和 false 会被保留。
- 视频创建接受 JSON 或 multipart/form-data，此处展示 JSON 示例。使用 multipart 时，每个字段只能填写一个值，input_reference 只能上传一个文件。
- 使用 multipart 时，将 parameters 或 metadata 编码为 JSON 字符串，保留布尔值与数字设置的类型。
- 使用 seconds 或 metadata.parameters.duration，冲突的时长会被拒绝。分辨率建议使用此模型的准确 resolution 值。
- 使用视频 ID 轮询至 completed 或 failed；完成后再从 /videos/{id}/content 下载，返回的是文件字节。
- 将 example.com 替换为自己可访问的参考图片地址。原生图片字段与 images/input_reference 别名选一种写法，不能重复提供。

## Responses API · 后台模式

`POST /v1/responses`

### 最小调用

#### cURL

```bash
curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/responses" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "background": true,
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "A quiet lakeside at sunrise"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/reference.png"
        }
      ]
    }
  ]
}
JSON
```

#### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

payload = json.loads("{\n  \"model\": \"lightricks/ltx-2.5/image-to-video/pro\",\n  \"background\": true,\n  \"input\": [\n    {\n      \"role\": \"user\",\n      \"content\": [\n        {\n          \"type\": \"input_text\",\n          \"text\": \"A quiet lakeside at sunrise\"\n        },\n        {\n          \"type\": \"input_image\",\n          \"image_url\": \"https://example.com/reference.png\"\n        }\n      ]\n    }\n  ]\n}")

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/responses",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

#### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "background": true,
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "A quiet lakeside at sunrise"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/reference.png"
        }
      ]
    }
  ]
})
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 请求参数

- `model` — **必填**; `string`. 使用此处显示的完整公开模型 ID。
  - 约束: `const = "lightricks/ltx-2.5/image-to-video/pro"`

- `background` — **必填**; `boolean`. 此视频模型必须设置为 true。
  - 约束: `const = true`

- `input` — **必填**; `string | array<object>`. 使用 input_image 提供参考图片；模型要求提示词时，同时提供 input_text。

### input 中的字段

仅在提供 input 时适用；子字段必填不代表可选的父字段也必填。

- `input[].role` — **可选**; `string`. 输入内容对应的消息角色。
  - 约束: `example = "user"`

- `input[].content` — **必填**; `array<object>`. 生成提示词及参考图片内容。

### input[].content 中的字段

仅在提供 input[].content 时适用；子字段必填不代表可选的父字段也必填。

- `input[].content[].type` — **必填**; `string`. 文字使用 input_text，参考图片使用 input_image。
  - 约束: `enum = ["input_text","input_image"]`

- `input[].content[].text` — **条件必填**; `string`. 描述主体、场景和期望生成的内容。
  - type 为 input_text 时必填。

- `input[].content[].image_url` — **条件必填**; `string`. 参考图片；提供可访问的 HTTP(S) 地址或 base64 图片 data URL。
  - type 为 input_image 时必填。



- `stream` — **可选**; `boolean`. 此视频模型不支持流式输出。
  - 默认: `false`
  - 约束: `const = false`

- `metadata` — **可选**; `object`. 模型生成设置的可选容器。

### metadata 中的字段

仅在提供 metadata 时适用；子字段必填不代表可选的父字段也必填。

- `metadata.parameters` — **可选**; `object`. 仅接受下方列出的模型设置。

### metadata.parameters 中的字段

仅在提供 metadata.parameters 时适用；子字段必填不代表可选的父字段也必填。

- `metadata.parameters.camera_motion` — **可选**; `string`. 期望的镜头运动预设。
  - 约束: `enum = ["dolly_in","dolly_out","dolly_left","dolly_right","jib_up","jib_down","static","focus_shift"]`

- `metadata.parameters.resolution` — **可选**; `string`. 输出分辨率。允许值取决于此模型，并区分大小写。
  - 默认: `"1080p"`
  - 约束: `enum = ["720p","1080p"]`

- `metadata.parameters.duration` — **可选**; `integer`. 请求的视频时长，单位为秒。
  - 默认: `8`
  - 约束: `enum = [6,8,10]`

- `metadata.parameters.aspect_ratio` — **可选**; `string`. 期望的输出宽高比。
  - 默认: `"auto"`
  - 约束: `enum = ["auto","16:9","9:16"]`

- `metadata.parameters.generate_audio` — **可选**; `boolean`. 是否请求生成音频。
  - 默认: `true`

- `metadata.parameters.end_image_url` — **可选**; `string`. 可选尾帧图片；同时需要提供起始参考图片。

- `metadata.parameters.fps` — **可选**; `integer`. 期望的每秒帧数。
  - 默认: `25`
  - 约束: `enum = [24,25,50]`



### 响应示例

响应示例仅展示结构；ID、URL 和数值为占位内容。

#### 后台任务响应

```json
{
  "id": "resp_EXAMPLE",
  "object": "response",
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "status": "queued",
  "background": true,
  "output": [],
  "usage": null
}
```

#### 完成响应

```json
{
  "id": "resp_EXAMPLE",
  "object": "response",
  "model": "lightricks/ltx-2.5/image-to-video/pro",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "<video controls src=\"MEDIA_CONTENT_URL\"></video>",
          "annotations": []
        }
      ]
    }
  ]
}
```

### 后续请求

#### 获取后台任务结果

使用返回的响应 id 查询；排队时 output 为空，完成后包含生成文件地址。

##### cURL

```bash
curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/responses/$SCENEPOND_RESPONSE_ID" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/responses/" + quote(os.environ["SCENEPOND_RESPONSE_ID"], safe="") + "",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_RESPONSE_ID) throw new Error("Set SCENEPOND_RESPONSE_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/responses/" + encodeURIComponent(process.env.SCENEPOND_RESPONSE_ID) + "", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 调用注意事项

- 每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。
- 此视频模型的 Responses 仅支持后台模式；未填写 background、设为 false 或 stream:true 都会被拒绝。文本模型的 Responses 使用不同规则。
- 将 SCENEPOND_RESPONSE_ID 设为返回的 id，查询至 completed 或 failed。
- 完成后 output_text 中包含视频元素和网关文件地址。请解析其中的地址，不要直接插入未经信任的 HTML。
- 此媒体适配器的 Responses Token 用量仅用于协议兼容；视频生成仍按配置的任务价格计费。
- 使用 metadata.parameters 填写本页的生成设置；tools、reasoning、temperature、max_output_tokens 等文本选项不控制 Fal 生成。
- 将 example.com 替换为自己可访问的参考图片地址。原生图片字段与 images/input_reference 别名选一种写法，不能重复提供。

## 资料来源

- [上游模型参数规范](https://fal.ai/models/fal-ai/ltx-2.5/image-to-video/pro/api)