# Scenepond API — API 文档

原始页面: https://open.scenepond.ai/zh/docs

使用网关地址和 Scenepond API Key，将应用接入已启用的模型。

## 1. 准备 API Key

在用户控制台创建密钥，保存到服务器的 SCENEPOND_API_KEY 环境变量中。网站登录会话不能作为 API Key 使用。

```bash
export SCENEPOND_API_KEY="YOUR_SCENEPOND_API_KEY"
```

## 2. 设置 API 地址

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

使用 Authorization: Bearer 携带 API Key。请使用 HTTPS，不要把密钥写进浏览器代码或 URL。

## 3. 发起请求

此示例使用 deepseek-flash。发送请求前，请确认 API 密钥具有访问权限，且账户余额充足。

### cURL

```bash
curl "https://scenepond-api-production.up.railway.app/v1/chat/completions" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "deepseek-flash",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "stream": false
}
JSON
```

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SCENEPOND_API_KEY"],
    base_url="https://scenepond-api-production.up.railway.app/v1"
)
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "deepseek-flash",
    messages: [{ role: "user", content: "Hello!" }],
    stream: false
  })
});
if (!response.ok) throw new Error(`API error: ${response.status}`);
const result = await response.json();
console.log(result.choices[0].message.content);
```

示例使用 chat completions 协议。图片、视频和任务 API 可能使用不同请求格式，接入前请确认模型接口和已配置供应商。

## 异步任务

图片与视频任务会在生成完成前返回 ID。提交一次并保存 ID，轮询状态，成功后再获取生成文件。

- `POST /v1/tasks/fal`: 提交符合该模型参数规范的生成请求，返回 task_id。
- `GET /v1/tasks/{task_id}`: 查看状态、进度和 fail_reason；此接口不返回生成文件。
- `GET /v1/tasks/{task_id}/artifacts`: 状态为 SUCCESS 后，读取结果列表及各文件的 content_url。

在模型页面查看准确的必填字段、可选生成设置，以及 Video 或 Responses 兼容协议。视频 Responses 必须设置 background:true；文本模型的 Responses 使用不同规则。

使用同一账户的 API Key 获取任务结果。等待 SUCCESS 或 completed 后再下载；出现 FAILURE 或 failed 时检查错误。请求超时后，不要盲目重复付费 POST 请求。

## 4. 查看余额与用量

请求由现有后端结算。调用前比较模型价格，调用后在用量记录中查看实际费用。

[模型与价格](https://open.scenepond.ai/zh/models)

[使用记录](https://open.scenepond.ai/zh/account)

## 处理 API 错误

- `400`: 检查模型 ID、必填字段、数据类型和参数允许值。
- `401`: 检查 API Key 是否正确且已启用。
- `403`: 检查密钥限制和模型权限。
- `429`: 遵循返回的重试间隔，并降低请求频率。
- `5xx`: 检查错误响应，避免盲目重试付费生成请求。

## 工具接入

在工具接入指南中查看 Hermes、OpenClaw、IDE、Dify 或 n8n 的配置步骤。

[查看接入指南](https://open.scenepond.ai/zh/integrations)

## 模型 API 文档

选择模型，查看其 API 协议和请求示例。

- [Wan 3.0 Prime](https://open.scenepond.ai/zh/docs/models/alibaba%2Fwan-3.0-prime%2Fimage-to-video.md) — `alibaba/wan-3.0-prime/image-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/alibaba%2Fwan-3.0-prime%2Fimage-to-video#api)
- [Wan 3.0 Prime](https://open.scenepond.ai/zh/docs/models/alibaba%2Fwan-3.0-prime%2Ftext-to-video.md) — `alibaba/wan-3.0-prime/text-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/alibaba%2Fwan-3.0-prime%2Ftext-to-video#api)
- [Wan 3.0](https://open.scenepond.ai/zh/docs/models/alibaba%2Fwan-3.0%2Fimage-to-video.md) — `alibaba/wan-3.0/image-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/alibaba%2Fwan-3.0%2Fimage-to-video#api)
- [Wan 3.0](https://open.scenepond.ai/zh/docs/models/alibaba%2Fwan-3.0%2Ftext-to-video.md) — `alibaba/wan-3.0/text-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/alibaba%2Fwan-3.0%2Ftext-to-video#api)
- [FLUX 3 Draft](https://open.scenepond.ai/zh/docs/models/blackforestlabs%2Fflux-3%2Fimage-to-video%2Fdraft.md) — `blackforestlabs/flux-3/image-to-video/draft` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/blackforestlabs%2Fflux-3%2Fimage-to-video%2Fdraft#api)
- [FLUX 3 Draft](https://open.scenepond.ai/zh/docs/models/blackforestlabs%2Fflux-3%2Ftext-to-video%2Fdraft.md) — `blackforestlabs/flux-3/text-to-video/draft` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/blackforestlabs%2Fflux-3%2Ftext-to-video%2Fdraft#api)
- [DeepSeek Flash](https://open.scenepond.ai/zh/docs/models/deepseek-flash.md) — `deepseek-flash` · openai, openai-response, anthropic · [原始页面](https://open.scenepond.ai/zh/models/deepseek-flash#api)
- [DeepSeek V4 Pro](https://open.scenepond.ai/zh/docs/models/deepseek-v4-pro.md) — `deepseek-v4-pro` · openai, openai-response, anthropic · [原始页面](https://open.scenepond.ai/zh/models/deepseek-v4-pro#api)
- [Gemini Omni 1.1 Flash](https://open.scenepond.ai/zh/docs/models/google%2Fgemini-omni-flash%2Fv1.1%2Fimage-to-video.md) — `google/gemini-omni-flash/v1.1/image-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/google%2Fgemini-omni-flash%2Fv1.1%2Fimage-to-video#api)
- [Gemini Omni 1.1 Flash](https://open.scenepond.ai/zh/docs/models/google%2Fgemini-omni-flash%2Fv1.1%2Ftext-to-video.md) — `google/gemini-omni-flash/v1.1/text-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/google%2Fgemini-omni-flash%2Fv1.1%2Ftext-to-video#api)
- [LTX-2.5 Fast](https://open.scenepond.ai/zh/docs/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Ffast.md) — `lightricks/ltx-2.5/image-to-video/fast` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Ffast#api)
- [LTX-2.5 Pro](https://open.scenepond.ai/zh/docs/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Fpro.md) — `lightricks/ltx-2.5/image-to-video/pro` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Fpro#api)
- [LTX-2.5 Fast](https://open.scenepond.ai/zh/docs/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Ffast.md) — `lightricks/ltx-2.5/text-to-video/fast` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Ffast#api)
- [LTX-2.5 Pro](https://open.scenepond.ai/zh/docs/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Fpro.md) — `lightricks/ltx-2.5/text-to-video/pro` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Fpro#api)
- [Muse Image](https://open.scenepond.ai/zh/docs/models/meta%2Fmuse-image%2Ftext-to-image.md) — `meta/muse-image/text-to-image` · fal-task · [原始页面](https://open.scenepond.ai/zh/models/meta%2Fmuse-image%2Ftext-to-image#api)
- [MiniMax H3 Max Turbo](https://open.scenepond.ai/zh/docs/models/minimax%2Fh3-max-turbo%2Fimage-to-video.md) — `minimax/h3-max-turbo/image-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/minimax%2Fh3-max-turbo%2Fimage-to-video#api)
- [MiniMax H3 Max Turbo](https://open.scenepond.ai/zh/docs/models/minimax%2Fh3-max-turbo%2Ftext-to-video.md) — `minimax/h3-max-turbo/text-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/minimax%2Fh3-max-turbo%2Ftext-to-video#api)
- [MiniMax H3 Max](https://open.scenepond.ai/zh/docs/models/minimax%2Fh3-max%2Fimage-to-video.md) — `minimax/h3-max/image-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/minimax%2Fh3-max%2Fimage-to-video#api)
- [MiniMax H3 Max](https://open.scenepond.ai/zh/docs/models/minimax%2Fh3-max%2Ftext-to-video.md) — `minimax/h3-max/text-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/minimax%2Fh3-max%2Ftext-to-video#api)
- [MiniMax H3](https://open.scenepond.ai/zh/docs/models/minimax%2Fh3%2Fimage-to-video.md) — `minimax/h3/image-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/minimax%2Fh3%2Fimage-to-video#api)
- [MiniMax H3](https://open.scenepond.ai/zh/docs/models/minimax%2Fh3%2Ftext-to-video.md) — `minimax/h3/text-to-video` · fal-task, openai-video, openai-response · [原始页面](https://open.scenepond.ai/zh/models/minimax%2Fh3%2Ftext-to-video#api)
- [Recraft V4.1 Flash](https://open.scenepond.ai/zh/docs/models/recraft%2Fv4.1%2Fflash%2Ftext-to-image.md) — `recraft/v4.1/flash/text-to-image` · fal-task · [原始页面](https://open.scenepond.ai/zh/models/recraft%2Fv4.1%2Fflash%2Ftext-to-image#api)
- [Grok Imagine Image 2.0](https://open.scenepond.ai/zh/docs/models/xai%2Fgrok-imagine-image%2Fv2.0%2Fedit.md) — `xai/grok-imagine-image/v2.0/edit` · fal-task · [原始页面](https://open.scenepond.ai/zh/models/xai%2Fgrok-imagine-image%2Fv2.0%2Fedit#api)
- [Grok Imagine Image 2.0](https://open.scenepond.ai/zh/docs/models/xai%2Fgrok-imagine-image%2Fv2.0%2Ftext-to-image.md) — `xai/grok-imagine-image/v2.0/text-to-image` · fal-task · [原始页面](https://open.scenepond.ai/zh/models/xai%2Fgrok-imagine-image%2Fv2.0%2Ftext-to-image#api)