QUICKSTART · 5 MIN

快速开始：5 分钟跑通第一个请求

拿 Key → 发第一个请求 → 查余额。视频与图像统一走 /v1/videos 任务接口（提交、轮询 / webhook），基础地址 https://api.modapis.com/v1。

1. 注册并获取 API Key

打开控制台，用 GitHub 或 Google 账号（OAuth）注册， Free 档送 50 credits（一次性，≈1 条 Kling 5s 或 3 张 Nano Banana Pro），无需绑卡。想先看接口长什么样？Sandbox 免注册，mock 通道零成本联调。

在「API Keys」页创建一个 Key，设置额度上限后复制保存。Key 只在创建时完整显示一次。代码里通过环境变量引用，不要写进仓库：

export MODAPIS_API_KEY="um-xxxxxxxxxxxxxxxx"

2. 第一个请求（图像示例 · 统一任务接口）

视频与图像模型走同一个任务接口：POST /v1/videos 提交，返回任务 id；轮询 GET /v1/videos/{id} 直到 status: "completed"（queued → in_progress → completed；失败终态 failed 带 error 对象），取顶层 url 字段；也可以在提交时带 callback_url，任务完成由 webhook 主动推送（全档免费）。按张计 credits，失败不计费。

统一任务接口

# Nano Banana Pro · 统一任务接口（图像与视频同端点 /videos）
curl https://api.modapis.com/v1/videos \
  -H "Authorization: Bearer $MODAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "把照片里的夏天改成冬天，保持人物与构图不变"
  }'

# 轮询：GET https://api.modapis.com/v1/videos/{id} → status:"completed" 后取顶层 url

import os, requests, time

API = "https://api.modapis.com/v1"
H = {"Authorization": f"Bearer {os.environ['MODAPIS_API_KEY']}"}

def call(method, url, **kw):              # 统一出口：非 200 直接给可读错误
    r = requests.request(method, url, headers=H, timeout=60, **kw)
    if r.status_code != 200:
        raise SystemExit(f"HTTP {r.status_code}: {r.text}")  # 401 = Key 无效/被吊销
    return r.json()

task = call("POST", f"{API}/videos", json={
    "model": "nano-banana-pro",
    "prompt": "把照片里的夏天改成冬天，保持人物与构图不变",
})

while task["status"] != "completed":        # queued → in_progress → completed
    if task["status"] == "failed":
        raise SystemExit(task.get("error"))  # 失败终态：message + code
    time.sleep(3)
    task = call("GET", f"{API}/videos/{task['id']}")

print(task["url"])                          # 成品地址在顶层 url 字段

const API = "https://api.modapis.com/v1";
const H = { Authorization: `Bearer ${process.env.MODAPIS_API_KEY}` };

const call = async (url, opts = {}) => {
  const r = await fetch(url, { headers: H, ...opts });
  if (!r.ok) throw new Error(`HTTP ${r.status}: ${await r.text()}`);
  return r.json();
};

let task = await call(`https://api.modapis.com/v1/videos`, {
  method: "POST",
  body: JSON.stringify({ model: "nano-banana-pro", prompt: "把照片里的夏天改成冬天，保持人物与构图不变" }),
});

while (task.status !== "completed") {        // queued → in_progress → completed
  if (task.status === "failed") throw new Error(JSON.stringify(task.error));
  await new Promise(r => setTimeout(r, 3000));
  task = await call(`https://api.modapis.com/v1/videos/${task.id}`);
}
console.log(task.url);                       // 成品地址在顶层 url 字段

模型 nano-banana-pro → /models/nano-banana-pro-api

3. 生成一段视频（同一接口，只换 model）

视频与图像同走任务接口：把 model 换成 veo-3.1 / kling-3.0 即可，提交、轮询、webhook 的结构与错误处理完全一致——一个 handler 覆盖整个目录。

统一 REST

# Kling 3.0 · 统一 REST：提交任务
curl https://api.modapis.com/v1/videos \
  -H "Authorization: Bearer $MODAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "prompt": "一只柯基在雨后的东京街头奔跑，霓虹反光，电影感运镜",
    "duration": 5,
    "resolution": "1080p"
  }'

# 轮询：GET https://api.modapis.com/v1/videos/{id} → status:"completed" 后取顶层 url

import os, requests, time

API = "https://api.modapis.com/v1"
H = {"Authorization": f"Bearer {os.environ['MODAPIS_API_KEY']}"}

def call(method, url, **kw):              # 统一出口：非 200 直接给可读错误
    r = requests.request(method, url, headers=H, timeout=60, **kw)
    if r.status_code != 200:
        raise SystemExit(f"HTTP {r.status_code}: {r.text}")  # 401 = Key 无效/被吊销
    return r.json()

task = call("POST", f"{API}/videos", json={
    "model": "kling-3.0",
    "prompt": "一只柯基在雨后的东京街头奔跑，霓虹反光，电影感运镜",
})

while task["status"] != "completed":        # queued → in_progress → completed
    if task["status"] == "failed":
        raise SystemExit(task.get("error"))  # 失败终态：message + code
    time.sleep(3)
    task = call("GET", f"{API}/videos/{task['id']}")

print(task["url"])                          # 成品地址在顶层 url 字段

const API = "https://api.modapis.com/v1";
const H = { Authorization: `Bearer ${process.env.MODAPIS_API_KEY}` };

const call = async (url, opts = {}) => {
  const r = await fetch(url, { headers: H, ...opts });
  if (!r.ok) throw new Error(`HTTP ${r.status}: ${await r.text()}`);
  return r.json();
};

let task = await call(`https://api.modapis.com/v1/videos`, {
  method: "POST",
  body: JSON.stringify({ model: "kling-3.0", prompt: "一只柯基在雨后的东京街头奔跑，霓虹反光，电影感运镜" }),
});

while (task.status !== "completed") {        // queued → in_progress → completed
  if (task.status === "failed") throw new Error(JSON.stringify(task.error));
  await new Promise(r => setTimeout(r, 3000));
  task = await call(`https://api.modapis.com/v1/videos/${task.id}`);
}
console.log(task.url);                       // 成品地址在顶层 url 字段

模型 kling-3.0 → /models/kling-3.0-api

4. 查询余额与用量

控制台「费用中心」可看 credits 余额、按模型/按天的用量曲线；账单逐条对应请求 ID，可下载 CSV 与你的网关日志对账。按量充值的 credits 12 个月有效；订阅币滚存 1 期（见定价页）。

5. 排障与可观测

每个请求在控制台日志里留痕：模型、credits、耗时、状态，按 Key 与时间筛选；失败任务自动退 credits 并留有记录。各通道实时健康度与历史事件公开在状态页，不打哑谜。任务类接口（视频 / 音乐）的每个应答都带 relay 字段（如 {"upstream":"kie","model":"kling-3.0"}），标明这次由哪个上游服务——配合响应头 X-Oneapi-Request-Id，反馈问题时带上两者，我们能定位到你这次请求实际走的通道与重试轨迹。

6. 常见问题

错误响应统一为 {"error": {"message", "code", "type"}}：message 可直接展示；上面 Python / JS 示例已按此口径处理——非 200 会抛出含状态码与响应体的可读错误，而不是崩在字段访问上。
401 Unauthorized：检查 Header 是否为 Authorization: Bearer $MODAPIS_API_KEY，Key 是否被吊销。
429 Too Many Requests：并发与 RPM 限制随档位（Free 1 / Starter 3 / Studio 10 / Team 更高）；批量任务建议排队提交。
超时/5xx 不计费：任务失败 credits 自动退回，可在账单里核对。

下一步

浏览模型目录，看每个模型的 credits 费率与示例。
从其他平台迁移？看fal.ai 替代的迁移 diff。
关注更新日志：新模型发布当天上线。

一个 Key，五分钟后跑通全部模型

Sandbox 免注册先试，Free 档 50 credits 起步，无需绑卡。

免费获取 API Key → 先看文档