# 推荐：请求头（避免 Key 出现在 URL、日志和浏览器历史中）
curl -H "X-API-Key: pk-xxxxxxxxxxxxxxxx" \
  https://star-advice.com/openapi/v1/account/balance

# URL 参数：适用于免登录打开页面或无法设置请求头的客户端
https://star-advice.com/workbench/video?apikey=pk-xxxxxxxxxxxxxxxx
https://star-advice.com/openapi/v1/account/balance?apiKey=pk-xxxxxxxxxxxxxxxx

API Key 可在平台控制台创建和管理。 apikey 与 apiKey 均可使用。Key 支持权限范围、每分钟限流和每日积分上限；无效 Key 返回 HTTP 401。

创建业务记录、触发 AI 或扣费的接口还必须携带 Idempotency-Key 请求头；网络重试时复用原值，同一个值不能用于不同请求。

如何阅读接口文档

交互式 API 参考中的每个接口都包含操作说明、路径/查询/请求头参数、请求体字段与示例、成功响应以及通用错误响应。

文档区域	内容	使用建议
Parameters	路径、查询和请求头参数，包括 `Idempotency-Key`	带默认值的查询参数可省略
Request body	JSON 字段、约束、必填规则和可复制示例	只传需要修改的可选字段
Responses	200 成功结构，以及 400/401/403/404/409/429/500 错误说明	始终先判断 `success`
Schemas	请求和返回对象中每个字段的类型及业务含义	异步任务还需判断 `data.status`

调用模式：异步任务

图片、语音、素材和 AI 镜头采用异步任务模式：创建后返回 taskId，通过轮询获取结果，不需要公网回调地址。

状态	含义	操作建议
PENDING	任务已创建，等待执行	等待 2~3 秒后轮询
PROCESSING	任务执行中	继续每 2~3 秒轮询
SUCCESS	任务成功	读取结果数据，停止轮询
FAILED	任务失败	查看 errorMessage，调整参数后重试

视频脚本、BGM 与动态镜头

GENERAL 与 GENERAL_BLANK 始终保留最基础的视频脚本流程。产品广告、商业推广、知识讲解、品牌故事和情节短剧是可选增强；使用 GET /openapi/v1/video-director-presets 查询可用模式和常用模板。

项目可保存当前用户私有的 characters，分镜通过 characterRefs 绑定实际出现的角色或产品。参考图只在生成对应图片时使用，不与其他用户共享，也不参与项目成功判断。

项目名称、全局音色和全局 BGM 可通过 PATCH /openapi/v1/video-projects/{projectId} 随时修改，包括制作中和已完成的项目。单个分镜可独立编辑；字幕行可以覆盖全局音色，或用 inheritProjectVoice=true 恢复继承。单个分镜通过 PATCH .../scenes/{sceneId}/background-music 配置独立音乐。

分镜 BGM 模式	含义	典型用途
`INHERIT`	继承项目全局 BGM	默认模式；保持全片音乐统一
`OVERRIDE`	使用该分镜指定的 `bgmId`	转场、高潮或特殊情绪
`MUTE`	该分镜不播放 BGM	对白、留白或纯环境声

推荐默认值：首镜淡入 2 秒，普通镜间衔接 0.4 秒，尾镜从 72% 位置开始抬升 2.5 dB 并淡出 3 秒；有人声时自动压低 BGM。动态镜头是可选项：主要图片和配音生成完成后项目即为 SUCCESS，动态镜头未生成或失败都不影响项目成功状态。

除一键生成全部素材外，也可以按单分镜生成图片、按单分镜生成全部配音，或只生成一条字幕配音。字幕或音色被修改后，仅对应配音回到待生成状态。

导出 JSON 字段

使用 GET /openapi/v1/video-projects/{projectId}/manifest 获取对象形式的合成清单；使用 /export 获取兼容的 JSON 字符串。

字段	说明
`project.directorMode / scriptTemplate`	AI 导演模式和套用的脚本模板；GENERAL / GENERAL_BLANK 代表基础通用脚本
`project.characters[]`	项目私有角色或产品参考，包括稳定外观描述与最多 3 张参考图
`scenes[].storyBeat / shotType / cameraMotion`	分镜叙事作用、镜头景别和镜头运动建议
`scenes[].characterRefs`	该分镜绑定的项目角色 ID；identityLock 控制身份一致性约束
`backgroundMusic`	根级全局 BGM，包含 enabled、url、volume、fadeInSeconds、fadeOutSeconds、duckUnderVoice
`scenes[].backgroundMusic`	分镜 BGM 模式、来源、首尾镜标志、地址、音量、淡入淡出、衔接和尾段增强参数
`scenes[].visual.imageUrl`	分镜静态图片公网地址
`scenes[].visual.videoUrl`	可选动态镜头成功后的公网下载地址；未生成时为 null
`scenes[].dubbings[]`	字幕、配音公网地址及时间轴定位

{
  "backgroundMusic": {"enabled": true, "url": "https://cdn.example.com/bgm.mp3", "volume": 0.3},
  "scenes": [{
    "sceneIndex": 1,
    "visual": {"type": "video", "imageUrl": "https://cdn.example.com/scene.jpg", "videoUrl": "https://cdn.example.com/scene.mp4"},
    "backgroundMusic": {"mode": "INHERIT", "isOpeningScene": true, "fadeInSeconds": 2.0},
    "dubbings": [{"text": "欢迎观看", "audioUrl": "https://cdn.example.com/voice.mp3", "timelineStartMs": 0}]
  }]
}

通用响应结构

所有接口统一返回以下 JSON 结构：

字段	类型	说明
`success`	boolean	请求是否成功
`error.code`	string / null	稳定错误码，例如 `INVALID_API_KEY`、`BUSINESS_ERROR`
`error.message`	string / null	错误描述，内容以服务端实际返回为准
`error.fieldErrors`	array / null	字段级错误（当前 OpenAPI 暂未拆分，通常为 null）
`data`	object / null	成功时返回业务数据，失败时为 null
`traceId`	string	请求追踪 ID，排查问题时请提供给平台

准备好开始接入了吗？

查看交互式 API 文档，直接在线调试每个接口

打开 API 参考

常见问题

创建任务后为什么没有立刻返回图片？

图片生成是异步任务，创建接口只负责接单并返回 taskId，需要通过查询接口轮询获取最终结果。

一次请求会返回几张图？

当前版本固定为单次请求生成单张图片，查询结果只返回一个 imageUrl。

任务多久超时？

当前平台默认在 2 分钟内完成轮询；如果上游长时间未完成，任务会被判定为失败并停止轮询。

需要排查问题，应该提供什么信息？

请提供接口返回的 traceId 字段，平台可以根据 traceId 快速定位请求链路。