SpaceSkills

开发者

文生视频 API

一次 POST,把一句话变成一条带原生声音的短片。按成片秒数计费 —— 固定每秒 40 积分,再无别的费用。

三步开始

1

领一把 key

登录后到账户页新建 API 密钥,只显示一次,记得当场存好。这把 key 同时能调导演 API。

2

充值

同一个页面预付积分。1 美元 = 1,000 积分,12 个月内有效。

3

开始调用

POST 一句提示词,立刻拿到 job_id,轮询到出片。出片以分钟计 —— 请按「任务」来写,别按「请求」来写。

去我的账户 先在网页上试一条

怎么收费

成片固定每秒 40 积分,不分时段。没有单次调用费,没有分辨率档位,失败不收费。定价页上的白天 / 夜间价只适用于网页端,API 不适用,也不使用免费秒数。

时长积分出片耗时
4 秒160约 3 分钟
8 秒320约 8 分钟
10 秒400约 10 分钟
15 秒600约 17 分钟

三种模式同价,画幅也不影响价格。提交时预扣,成功时预扣即为实扣;失败或取消当分钟全额退回。出片耗时是估计不是承诺 —— 真正作数的是返回里的 deliver_by。

三种出片方式

同一个模型、同一个价、同一个端点,靠 mode 选。

mode做什么要给什么
text一句话出片。默认值,不传 mode 就是它。prompt
animate让一张照片动起来。给第一帧;再给一张最后一帧,它就在两张之间运动。first_frame,可选 last_frame
cast让指定的人 / 物 / 画风 / 声音出现在片子里。提示词里用 <Picture 1>、<Audio 1> 指代。ref_images 和 / 或 ref_audios

当前开放哪些模式,以 GET /v1/models 的返回为准。我们是一个一个放开的;没开的模式会明确返回 mode_unavailable,不会假装能用。

对口型

给 cast 模式一段参考音频,片子里的人就会把它说出来,口型跟着这段录音走。

竖屏、横屏与方屏

传 ratio。所有画幅同价、同耗时,所以按片子发到哪儿选,不用为省钱迁就。

ratio用在哪
16:9横屏。默认值,不传就是它。
9:16竖屏,给手机 —— 抖音、Reels、Shorts。
1:1方屏,给信息流。

要等多久,说实话

提交一个任务

curl -X POST https://spaceskills.shop/v1/videos \
  -H "Authorization: Bearer $SPACESKILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-clip-0001" \
  -d '{
    "prompt": "A red paper boat drifting on a calm pond at sunrise, soft golden light, gentle ripples on the water, slow push-in, cinematic",
    "duration_sec": 5
  }'
HTTP/1.1 202 Accepted
{
  "job_id": "vid_8Qk2ZrX1c0Nn",
  "status": "queued",
  "model": "h3/768p",
  "duration_sec": 5,
  "credits_held": 200,
  "balance": 9800,
  "queue_position": 1,
  "est_render_sec": 259,
  "deliver_by": "2026-09-09T14:31:07.000Z",
  "poll": "/v1/videos/vid_8Qk2ZrX1c0Nn"
}

返回 202,带 job_id 和预扣的积分。带上 Idempotency-Key,重试的 POST 会返回同一个任务,不会扣第二次钱。

curl https://spaceskills.shop/v1/videos/vid_8Qk2ZrX1c0Nn \
  -H "Authorization: Bearer $SPACESKILLS_API_KEY"
{
  "job_id": "vid_8Qk2ZrX1c0Nn",
  "status": "succeeded",
  "duration_sec": 5,
  "seed": 774512900183,
  "credits_held": 0,
  "credits_charged": 200,
  "output": {
    "url": "https://media.spaceskills.shop/relay/vid_8Qk2ZrX1c0Nn.mp4",
    "stored": true
  },
  "error": null,
  "created_at": "2026-09-09T14:21:44.910Z",
  "updated_at": "2026-09-09T14:25:12.338Z"
}

status 有五种:queued、running、succeeded、failed、cancelled。succeeded 时 output.url 就是已经混好音的成品 MP4。

图和音频怎么传

和导演 API 同一套写法:每个文件要么内联 base64,要么给一个我们去拉的 https 地址。

# cast: put a specific face, object or look in the shot
curl -X POST https://spaceskills.shop/v1/videos \
  -H "Authorization: Bearer $SPACESKILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "cast",
    "prompt": "The woman from <Picture 1> walks slowly through a rainy neon street at night, reflections on wet asphalt, rain and distant traffic, slow tracking shot",
    "duration_sec": 6,
    "ref_images": [
      { "name": "her.jpg", "url": "https://example.com/her.jpg" }
    ]
  }'

# animate: start from a photo
curl -X POST https://spaceskills.shop/v1/videos \
  -H "Authorization: Bearer $SPACESKILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "animate",
    "prompt": "The lake ripples as the sun sinks lower, drifting clouds, distant birdsong, slow push-in",
    "duration_sec": 5,
    "first_frame": { "name": "lake.jpg", "url": "https://example.com/lake.jpg" }
  }'

端点

端点做什么
GET /v1/models目录:时长区间、每秒单价、当前队列深度。免费,不需要 key。
POST /v1/videos提交提示词,预扣积分,返回 job_id。
GET /v1/videos/{id}查状态,出好了就一并给文件。
GET /v1/videos你最近 30 个任务和当前余额,用来对账。
POST /v1/videos/{id}/cancel还在排队时可取消,全额退回。已经开跑的显卡时间已经花掉了,不能取消。

请求字段

字段类型说明
prompt字符串这条片子要拍什么。8 到 20000 字。主体、动作、环境、光线、镜头 —— 按这个顺序写效果好。
duration_sec整数4 到 15。它是计价基准。不传默认 5。
mode字符串text、animate 或 cast。不传默认 text。
first_frame文件仅 animate,必填。片子从这一帧开始。
last_frame文件仅 animate,可选。片子在这一帧结束。
ref_images文件数组仅 cast,最多 4 张。在提示词里按你给的顺序用 <Picture 1> 起往后指代。
ref_audios文件数组仅 cast,最多 3 段。片中人物要说的声音 —— 对口型靠的就是它。用 <Audio 1> 指代。
ratio字符串16:9(默认)、9:16、1:1。同价,同耗时。以 GET /v1/models 的返回为准,这个列表会变。
model字符串默认 h3/768p,目前唯一在售的模型。
seed整数可选。种子、提示词、图都一样就能复现同一条片。不传就随机取一个,并在任务里回给你。

请求头:Authorization: Bearer sk_live_…,以及建议带上的 Idempotency-Key: <你自己生成的任意字符串>。同一账号下这个键会被记住,所以网络重试永远不会把同一条片买两次。

返回什么

提交、轮询、列表拿到的是同一个任务对象,只是当时已知的字段才有值。

怎么写提示词才出得好

模型读的是大白话,中英文都行。写得具体它就给你,堆形容词它就还你一堆平均值。

去看提示词库

出错的时候

错误码意思
unauthorizedkey 没带或不对。用 Authorization: Bearer sk_live_…
insufficient_credits余额不够。返回里会同时给出所需与现有两个数。
bad_params没给提示词、提示词过长,或者 duration_sec 不在 4~15 之间。
unknown_model没有这个在售模型。查 GET /v1/models。
mode_unavailable这个模式还没开放。返回里会列出当前开着的。
bad_material有图太大、不是真的 JPEG/PNG/WebP、拉不到,或者不是 https。消息里会说是哪一张。
payload_too_large请求体超过 24 MB。把图改成 https 链接,别内联 base64。
model_unavailable当前没有可用的渲染后端,通常是在换机。过几分钟再试,这次没有扣费。
capacity_deadline_infeasible队列已排到六小时以后。稍后再来,这次没有扣费。
idempotency_conflict这个 Idempotency-Key 已经被另一个请求占用了。
not_cancellable任务已经在跑或已经结束了。
rate_limited请求太密。Retry-After 会告诉你该等多久。

限额

想让导演替你出方案、把整部片出好? 看导演 Agent

有问题,或者哪里不对劲? 告诉我们