Castaly · 博客 · 使用指南

用代码生成 AI 视频：一个 Modelflare 密钥调用所有 Castaly 模型

用 curl 或 Python 创建、轮询并下载视频任务，调用图像模型，并了解 API 计费如何与 Castaly 共用余额和价格。

一个身穿宽大紫色大衣的人沿着空荡荡的长扶梯下行，四周是白色瓷砖隧道，画面来自一段 Kling O1 视频。

Castaly 创作台里的每个模型都能在你自己的代码里调用。Castaly 运行在你的 Modelflare 账号上，所以一个 Modelflare API 密钥就能调用所有图像和视频模型，按同样的公开价格、从同一份余额扣费。

本文从创建到下载完整走一遍视频请求，再介绍图像、计费以及你需要的文档。

准备工作

  1. API 密钥。 用登录 Castaly 的同一个账号登录 Modelflare，创建密钥。把它放进环境变量，下面的示例读取 MODELFLARE_API_KEY。
  2. 付费余额。 API 调用使用你与 Castaly 共用的付费余额，在任一网站充值即可。
  3. 模型文档页。 每个模型在 docs.modelflare.dev 都有一页，列出字段、限制，以及生成其样片的原始请求。

所有请求都发往 https://modelflare.dev/v1，并把密钥作为 Bearer token：

Authorization: Bearer YOUR_MODELFLARE_API_KEY

视频：创建、轮询、下载

视频生成是异步的：先创建任务，轮询到完成，再下载文件。

1. 创建任务

下面是生成 Seedance 2.5 文档页样片的原始请求：

curl https://modelflare.dev/v1/videos \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A small research submersible descends through the deep ocean, its headlights sweeping over a drifting field of bioluminescent jellyfish and a sunken stone archway. Camera follows from behind, particles float in the beams, blue-black water, calm and mysterious, photoreal, no text.",
    "seconds": "5",
    "duration": 5,
    "resolution": "1080p",
    "ratio": "16:9",
    "aspect_ratio": "16:9"
  }'

响应会立即返回任务 ID，状态为 queued：

{
  "id": "task_…",
  "task_id": "task_…",
  "object": "video",
  "model": "seedance-2.5",
  "status": "queued",
  "progress": 0
}

2. 轮询直到完成

curl https://modelflare.dev/v1/videos/TASK_ID \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

status 为 queued 或 in_progress 时继续轮询，到 completed 或 failed 时停止。失败的任务会带有 error_code 和 error_message。我们实测的任务耗时从约 1 分钟到 10 分钟出头不等，通常约 3 分钟，最久的是 10 秒 1080p 的 Seedance 2.5。建议每 10 到 15 秒轮询一次，不要连续请求。

3. 下载结果

curl -L https://modelflare.dev/v1/videos/TASK_ID/content \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -o clip.mp4

结果地址可能会过期，任务完成后请尽快保存文件。

上面请求的结果：seedance-2.5 · 5 秒 · 1080p · 16:9 —— 245,025 token，约 $3.54。

用 Python 写同样的流程

import os, time, requests

BASE = "https://modelflare.dev/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["MODELFLARE_API_KEY"]}

task = requests.post(BASE + "/videos", headers=HEADERS, json={
    "model": "kling-3.0",
    "prompt": "Stop-motion claymation style: a small orange clay fox sneaks "
              "through a miniature felt forest, no text.",
    "seconds": "5",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "aspect_ratio": "16:9",
}).json()

while True:
    status = requests.get(BASE + "/videos/" + task["task_id"], headers=HEADERS).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(15)

if status["status"] == "completed":
    video = requests.get(BASE + "/videos/" + task["task_id"] + "/content", headers=HEADERS)
    open("clip.mp4", "wb").write(video.content)
else:
    print(status.get("error_code"), status.get("error_message"))

各系列有自己的参数

上面这些简单字段足以完成文生视频，大多数视频模型的文档页也给出了这种格式的可用请求。除此之外，各系列使用各自服务商的原生结构，Modelflare 会原样转发：

系列 首尾帧、参考素材与其他参数
Seedance content[]，每个图片、视频或音频条目带 role；generate_audio；Seedance 2.5 用 omni_reference_task_type 做编辑和延长
可灵 model_name、mode、image、image_tail、video_url、image_list、sound
Wan 与 HappyHorse input（含 prompt 和 media[]）加 parameters；HappyHorse 支持 parameters.watermark: false
MiniMax H3 带角色的 content[]，加上 resolution、duration 和 ratio

不要在一个请求里混用不同结构，添加字段前先读模型文档：无效参数会返回带请求 ID 的 4xx 错误。

图像

GPT Image、Seedream 和 Wan 图像模型使用 OpenAI 风格的图像接口，一次调用直接返回结果：

curl https://modelflare.dev/v1/images/generations \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Picture-book illustration of a small fox carrying a paper lantern through a snowy birch forest at dusk, no text.",
    "size": "1536x1024",
    "quality": "medium",
    "n": 1
  }'

GPT Image 在 data[].b64_json 中返回 Base64 图片数据。Gemini 图像模型则使用 Google 原生的 generateContent 请求，接口和请求体见各自的文档页。

通过 API 计费

  • 与创作台同价。 按模型 ID 调用 API，按定价页上的公开价格计费。
  • 同样的预估、预扣与结算。 任务开始时网关预扣一笔预估，按服务商报告的用量结算并退回差额。失败的任务全额退款。
  • 赠送余额不同。 API 调用先扣 Modelflare 赠送余额，再扣付费余额。Castaly 赠送余额只能用于 Castaly 中的生成。

预扣和退款的细节见 Castaly 计费详解。

改用 AI 智能体

如果你使用 Claude Code、Codex 或其他能读取 SKILL.md 的智能体，Modelflare Media Skill 可以教会它选择模型、报出价格、提交请求、等待视频完成并保存结果。它由实时模型目录生成，模型列表和价格始终是最新的。Castaly 的连接任意智能体页面会一步步带你安装。

在 Castaly 设置智能体 →

常见问题

API 比创作台贵吗？

不贵。两者对同一模型 ID 使用同样的公开价格。

API 需要单独的账号或余额吗？

不需要。Castaly 运行在你的 Modelflare 账号上，在那里创建密钥，调用就会使用你与 Castaly 共用的付费余额。

怎么知道视频任务失败了？

轮询响应中 status 为 "failed"，并带有 error_code 和 error_message。失败任务的预扣会全额退回。

在哪里查看某个模型的具体字段？

在 docs.modelflare.dev 上它的页面里，那里列出所有字段、限制，以及生成真实样片的请求。