🎬 Artlist 视频生成 API · 完整使用文档

1. 概述

• 纯 REST + JSON 接口。支持 文生视频（text-to-video）、图生视频（image-to-video）、多图生视频（multi-to-video，最多 9 张）。
• 异步流程：POST /v1/videos 提交任务 → 轮询 GET /v1/videos/{id} 直到 status=done，得到视频直链。
• 按 积分（credits） 计费，价格由「模型 + 参数（分辨率/时长等）」实时决定。
• 共 40+ 个模型，可用 名称（推荐）或数字 ID 指定。
• 💻 网页控制台：/app — 无需写代码，粘贴 API Key 即可生成视频、查看余额与历史。
• 💵 价格表：/pricing — Seedance 2.0 各分辨率 × 时长的美元报价。

2. 认证

所有 /v1/* 接口都需在请求头带上密钥：

x-api-key: <你的 API_KEY>

密钥形如 alk_xxxxxxxx…。缺失 → 401 {"error":"Thiếu X-API-Key"}；无效/被撤销 → 401；账号被暂停 → 403。请勿泄露或多方共用（系统会检测异常并告警）。

3. 通用约定

4. 快速开始（3 步）

KEY="<你的 API_KEY>"
BASE="https://artlist-api.vercel.app"

# ① 提交（用模型名称，推荐）
curl -X POST "$BASE/v1/videos" -H "x-api-key: $KEY" -H 'content-type: application/json' -d '{
  "model": "seedance-2.0",
  "prompt": "a red panda skateboarding on a neon street at night, cinematic",
  "settings": { "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true },
  "maxCredits": 2000
}'
# → { "jobId":"019f…", "status":"processing", "credits":1200 }

# ② 轮询（每 3~5 秒一次），用上一步的 jobId
curl "$BASE/v1/videos/019f…" -H "x-api-key: $KEY"
# → status=processing … 最终 → status=done

# ③ 完成后取 videoUrl（完整保存！）
# { "status":"done", "videoUrl":"https://…mp4?Expires=…&Key-Pair-Id=…&Signature=…", "credits":1200 }

5. 选择模型（用名称，别记数字）

POST /v1/videos 里用 "model" 字段填模型名称或 slug（不区分大小写），无需记忆数字 ID：

{ "model": "Seedance 2.0", ... }      // 名称
{ "model": "seedance-2.0", ... }      // slug（推荐，稳定）
{ "modelGroupId": 358, ... }          // 数字 ID（仍兼容）

不填 model 时默认 Seedance 2.0。常用模型：

6.1 GET /v1/me — 账户信息

curl "$BASE/v1/me" -H "x-api-key: $KEY"

响应：

{
  "clientId": "019f1ecb-…",
  "name": "your-account",
  "credits": 12000,                     // 剩余积分
  "hasDefaultSession": false,
  "rateLimit": { "perMinute": 6, "perDay": 200 }
}

6.2 GET /v1/models — 模型列表

curl "$BASE/v1/models" -H "x-api-key: $KEY"

{ "models": [
  {
    "modelGroupId": 358,
    "slug": "seedance-2.0",
    "name": "Seedance 2.0",
    "credits": 800,                     // 基础积分（实际价按参数报价）
    "features": ["multi-to-video","image-to-video","text-to-video"],
    "capabilities": { "supportAudio": true, "supportImageUpload": true, "maxImageInputCount": 9, "hasEndFrame": true }
  },
  … 共 40+ 个
] }

6.3 GET /v1/models/{名称或ID} — 模型完整参数

路径可用 名称/slug 或 数字 ID：/v1/models/seedance-2.0 等价于 /v1/models/358。

curl "$BASE/v1/models/seedance-2.0" -H "x-api-key: $KEY"

{
  "modelGroupId": 358, "slug": "seedance-2.0", "name": "Seedance 2.0",
  "features": ["multi-to-video","image-to-video","text-to-video"],
  "params": [
    { "name":"resolution", "component":"dropdown_list",
      "options":[ {"value":"480p"}, {"value":"720p","default":true}, {"value":"1080p"}, {"value":"4k"} ] },
    { "name":"duration", "component":"dropdown_list",
      "options":[ {"value":"4"}, {"value":"5","default":true}, …, {"value":"15"} ] },
    { "name":"aspect_ratio", "options":[ {"value":"16:9","default":true}, {"value":"9:16"}, … ] },
    { "name":"generate_audio", "component":"toggle", "options":[{"value":"true","default":true},{"value":"false"}] },
    { "name":"image_url" }, { "name":"image_urls" }, { "name":"video_urls" }, { "name":"audio_urls" }, { "name":"end_frame" }
  ]
}

6.4 POST /v1/videos — 创建视频

必须提供 prompt（或放在 settings.prompt）。请求体字段：

* prompt 也可放在 settings.prompt；二者至少有其一。

响应（202）

{ "jobId":"019f…", "status":"processing", "videoUrl":null, "credits":1200, "createdAt":1782… }

示例 A · 文生视频

{ "model":"seedance-2.0", "prompt":"a red panda skateboarding, cinematic",
  "settings":{ "resolution":"1080p", "duration":8, "aspect_ratio":"16:9", "generate_audio":true }, "maxCredits":4000 }

示例 B · 图生视频（单图）

{ "model":"seedance-2.0", "prompt":"gentle zoom in, cinematic lighting",
  "image":"https://example.com/photo.jpg", "settings":{ "duration":5 }, "maxCredits":2000 }

示例 C · 多图生视频（最多 9 张 + 图片标签）

{ "model":"seedance-2.0",
  "prompt":"@img1 转场到 @img2，再到 @img3，平滑运镜，氛围配乐",
  "images":[ "https://example.com/1.jpg", "https://example.com/2.jpg", "https://example.com/3.jpg" ],
  "settings":{ "resolution":"720p", "duration":6, "generate_audio":true }, "maxCredits":2500 }

图片格式 png/jpg/webp，视频 mp4/mov/webm，音频 mp3/wav/m4a/aac。超出大小上限会返回 MEDIA_ERROR。

6.5 GET /v1/videos/{id} — 查询状态

每次调用都会向上游推进任务状态，建议 每 3~5 秒 轮询一次。

curl "$BASE/v1/videos/019f…" -H "x-api-key: $KEY"

// done 示例
{ "jobId":"019f…", "status":"done",
  "videoUrl":"https://cms-toolkit-artifacts.artlist.io/…mp4?Expires=…&Key-Pair-Id=…&Signature=…",
  "thumbnailUrl":"https://…jpg", "credits":1200, "createdAt":1782…, "updatedAt":1782… }

6.6 GET /v1/videos — 历史任务

curl "$BASE/v1/videos" -H "x-api-key: $KEY"    // → 你最近的任务数组（最多 100 条）

7. Seedance 2.0 完整参数（可选值）

8. 积分与计费

• 价格由 模型 + 参数 实时报价（如 1080p 比 720p 贵、时长越长越贵）。提交时按报价扣费。
• 生成 失败自动退款；提交失败（如报价失败）不扣费。
• maxCredits：报价超过则直接拒绝（402/400），保护你不被意外高价扣费。
• 余额随时查 GET /v1/me；不足返回 402。

9. 视频链接（videoUrl）

10. 错误码

// 错误响应统一格式
{ "error": "人类可读的错误信息", "code": "MACHINE_CODE" }

11. 限流

每个密钥有 每分钟 / 每天 请求上限，以及 并发任务 上限，超出返回 429。当前额度见 GET /v1/me。请勿多方共用同一密钥——系统会检测「同一 key 多 IP」等异常并告警。

12. 代码示例（完整轮询）

JavaScript (Node 18+/浏览器)

const BASE = "https://artlist-api.vercel.app", KEY = "<你的 API_KEY>";
const h = { "x-api-key": KEY, "content-type": "application/json" };

async function generate(body) {
  const r = await fetch(`${BASE}/v1/videos`, { method:"POST", headers:h, body:JSON.stringify(body) });
  const created = await r.json();
  if (!r.ok) throw new Error(created.error);
  let job = created;
  while (job.status === "processing") {
    await new Promise(s => setTimeout(s, 4000));
    job = await (await fetch(`${BASE}/v1/videos/${created.jobId}`, { headers:h })).json();
  }
  if (job.status !== "done") throw new Error(job.error || "failed");
  return job.videoUrl;
}

const url = await generate({
  model: "seedance-2.0",
  prompt: "a red panda skateboarding, cinematic",
  settings: { resolution: "720p", duration: 5, aspect_ratio: "16:9", generate_audio: true },
  maxCredits: 2000,
});
console.log(url);

Python (requests)

import time, requests
BASE, KEY = "https://artlist-api.vercel.app", "<你的 API_KEY>"
h = {"x-api-key": KEY}

def generate(body):
    r = requests.post(f"{BASE}/v1/videos", headers=h, json=body); r.raise_for_status()
    jid = r.json()["jobId"]
    while True:
        time.sleep(4)
        job = requests.get(f"{BASE}/v1/videos/{jid}", headers=h).json()
        if job["status"] != "processing":
            break
    if job["status"] != "done":
        raise RuntimeError(job.get("error", "failed"))
    return job["videoUrl"]

print(generate({
    "model": "seedance-2.0",
    "prompt": "a red panda skateboarding, cinematic",
    "settings": {"resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": True},
    "maxCredits": 2000,
}))

13. 最佳实践

• 用 model 名称/slug 而非数字 ID，代码更易读。
• 每次带 maxCredits，避免高分辨率/长时长意外扣费。
• 轮询间隔 3~5 秒；生成一般数十秒到几分钟。
• 遇到 503 SESSION_EXPIRED 时稍等重试（通常是上游临时波动）。
• 完整保存 videoUrl（含 query 参数），或及时转存到自己的存储。
• 集成前先 GET /v1/models/{名称} 确认该模型支持的参数与可选值。

14. 常见问题

Q：一定要传 chatSessionId 吗？

不用。留空系统会自动创建并复用。

Q：一次最多几张图？

Seedance 2.0 最多 9 张（images[]）。不同模型上限不同，见 capabilities.maxImageInputCount。

Q：视频链接会过期吗？

签名有效期约 10 年，正常使用无需担心；建议仍尽快转存。

Q：如何知道某模型支持哪些参数？

GET /v1/models/{名称} 返回该模型的 params（参数 + 可选值 + 默认值），实时权威。

如需调整额度、限流或更换密钥，请联系服务提供方。