API Reference

星港 API 文档

通过一个 API 调用平台上已授权的 AI 演员生成视频。所有请求走 HTTPS，返回 JSON。

Beta 内测中 —— 接口设计预览，正式开放前字段与价格可能调整。

获取 API Key

API 目前处于内测阶段。请先注册平台账号，然后通过页底「联系我们」提交内测申请（注明公司/团队、使用场景与预估调用量）。审核通过后将为你签发sk-star-开头的密钥。

Key 请保管在服务端环境变量中，不要暴露在前端代码或代码仓库里；泄露可随时申请轮换。

认证方式

所有请求在 Header 中携带 Bearer Token。基础地址：https://api.staract.ai/v1

AUTHENTICATION

Authorization: Bearer sk-star-********
Content-Type: application/json

生成视频

POST /videos —— 创建一个视频生成任务。任务异步执行，接口立即返回任务 ID。

参数	类型	必填	说明
actor_id	string	是	AI 演员 ID，从演员列表接口获取
prompt	string	是	画面描述（场景、动作、镜头语言）
duration	int	是	时长（秒），当前支持 3–10
resolution	string	否	720p（默认）或 1080p
webhook_url	string	否	任务完成后回调地址

REQUEST

curl https://api.staract.ai/v1/videos \
  -H "Authorization: Bearer sk-star-****" \
  -d '{
    "actor_id": "act_luna_8f2c",
    "prompt": "在雨后的东京街头微笑回眸，电影感",
    "duration": 5,
    "resolution": "1080p"
  }'

RESPONSE 202

{
  "id": "vid_9f31c7d2",
  "status": "queued",
  "actor_id": "act_luna_8f2c",
  "duration": 5,
  "created_at": "2026-07-04T12:00:00Z"
}

查询任务

GET /videos/{id} —— 轮询任务状态；也可以用 webhook 接收完成通知。状态流转：queued → processing → succeeded / failed

RESPONSE 200

{
  "id": "vid_9f31c7d2",
  "status": "succeeded",
  "video_url": "https://cdn.staract.ai/videos/vid_9f31c7d2.mp4",
  "expires_at": "2026-07-05T12:00:00Z",
  "billed_seconds": 5
}

video_url 为带签名的临时链接，24 小时内有效，请及时转存到你自己的存储。

演员列表

GET /actors —— 获取当前可调用的 AI 演员，支持按风格筛选（?style=fashion）。

RESPONSE 200

{
  "data": [
    {
      "id": "act_luna_8f2c",
      "name": "Luna",
      "styles": ["时尚", "广告"],
      "preview_url": "https://cdn.staract.ai/actors/act_luna_8f2c.jpg"
    }
  ],
  "has_more": true
}

计费说明

按实际生成秒数计费：标准 720p ¥0.8/秒，高清 1080p ¥1.2/秒，价格已包含演员形象授权成本。任务失败不扣费。企业批量与私有化部署请联系商务。

查看完整价格表 →

错误码

HTTP	code	说明
401	unauthorized	Key 无效或已过期
403	forbidden	演员未授权给当前 Key 或已下架
404	not_found	任务或演员不存在
422	invalid_request	参数校验失败，detail 字段说明原因
429	rate_limited	超出速率限制，见 Retry-After 响应头
451	content_rejected	prompt 未通过内容安全审核
500	server_error	服务端错误，可安全重试

合规说明

所有生成视频自动携带符合监管要求的 AI 生成标识，不可移除；
每条 prompt 与生成结果都会经过内容安全审核，违规请求返回 451 且计入风控记录；
演员形象由服务端注入，API 调用方无法获取演员原始素材；
演员授权撤回后，对应 actor_id 立即不可调用（403）。

查看 API 价格