创建任务后为什么没有立刻返回图片？
图片生成是异步任务，创建接口只负责接单并返回 taskId，需要通过查询接口轮询获取最终结果。
为个人工作台和 AI Agent 集成图片、语音、BGM 与视频脚本能力 —— 统一接口，按量计费。
AI 图片生成服务，支持文生图、参考图生成、多比例输出、高清档位。统一每张 5 积分，高清与参考图不加价。提交任务后异步获取结果。
查询系统音色，创建、试听和轮询个人克隆音色，并支持语音合成任务分页、状态轮询与失败重试。
使用文件接口上传音频后创建个人 BGM，支持查询、改名、删除，并可绑定到视频脚本。
保留基础通用脚本，并提供文案润色、AI 导演模式、结构化分镜、字幕级音色、按需素材生成和可选动态镜头。
录音会话管理服务，支持创建录音会话、上传音频样本、查询会话状态与结果。
统一文件上传服务，支持图片、音频、文档等格式。上传后返回可直接访问的 CDN 地址。
在平台控制台创建并保存您的 API Key
选择图片、语音、BGM 或视频脚本能力
通过请求头或 URL 参数传入 API Key
仅异步任务每 2~3 秒轮询一次
确认联调通过后，切换生产环境 API Key
除携带一次性会话 Token 的移动录音页外，API 请求和工作台页面均支持以下三种 API Key 传递方式：
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，调整参数后重试 |
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，动态镜头未生成或失败都不影响项目成功状态。
除一键生成全部素材外，也可以按单分镜生成图片、按单分镜生成全部配音，或只生成一条字幕配音。字幕或音色被修改后，仅对应配音回到待生成状态。
使用 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[] | 字幕、配音公网地址及时间轴定位 |
所有接口统一返回以下 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，排查问题时请提供给平台 |
图片生成是异步任务，创建接口只负责接单并返回 taskId，需要通过查询接口轮询获取最终结果。
当前版本固定为单次请求生成单张图片，查询结果只返回一个 imageUrl。
当前平台默认在 2 分钟内完成轮询；如果上游长时间未完成，任务会被判定为失败并停止轮询。
请提供接口返回的 traceId 字段，平台可以根据 traceId 快速定位请求链路。