创建一个实时导演 World。支持普通模式（自然语言 Prompt）和剧本模式（结构化 ScriptList），接口立即返回加密 World ID，World 在后台异步构建，客户端轮询构建进度直至完成。
适用范围
创建一个 Directing World。调用前请确认以下事项：
-
鉴权要求：仅支持主 API Key调用，临时 API Key 不可用（错误码
403003）。- 获取主 API Key：获取与配置 API Key。
-
调用模式：推荐使用异步模式。
- 异步模式（默认）：
async=true，接口立即返回encryptedWorldId，需轮询查询World构建状态获取进度。 - 同步模式：
async=false，服务端内部轮询（间隔 3s，最长 120s），构建完成后返回；超时则降级为异步，客户端继续轮询。
- 异步模式（默认）：
-
接口限制：本接口只能创建 Directing World，无需传
mode（服务端按2写入，传入非2返回400000）。creationModel支持simple（普通模式，默认）和scriptlist（剧本模式），进房版本固定为storyV2，aspectRatio和maxExperienceTimeSec固定为null。
HTTP调用
- 新加坡
- 美国（弗吉尼亚）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds调用时请将{WorkspaceId}替换为真实的Workspace ID。普通模式（creationModel=simple）
请求参数 |
|
Content-Typestring（必选）请求内容类型，固定为 application/json。 | |
Authorization string （必选）API Key 鉴权。仅支持主 API Key，以 sk- 开头，如 sk-xxx。通常配置为环境变量 $DASHSCOPE_API_KEY。临时 API Key（st- 开头）调用返回 403003。 | |
请求体（Request Body） | |
async boolean （可选）是否异步创建。默认 true：
| |
creationModel string （可选）创建子模式，普通模式传 simple（默认）。由您提供自然语言 prompt，服务端生成完整 45 拍剧本、首帧（可自带）和角色参考图。World 创建后，可在 Travel 阶段调用以下控制接口：
| |
eventStyle string （可选）仅 creationModel=simple 生效：选择剧本生成模板。默认 normal。可选值：
| |
refWorldId string （可选）基于已有 Directing World 衍生创建。必须是当前主账号名下的 Directing 加密 World ID；其它模型或其它主账号的 World 返回 403001。 | |
prompt string （必选）世界主题描述，支持中英文。非空，最长 2000 字符。 | |
resolution string （必选）视频分辨率。可选值：
| |
layout string （可选）镜头运动风格（镜头怎么动、切得多猛）。可选值：
| |
narrative string （可选）叙事风格（戏密不密、情绪强不强）。可选值：
| |
firstFrameImage object （可选）提供后直接复用为 World 首帧，跳过 AI 首帧生成。url 与 base64 二选一且互斥。图片约束如下：
属性 url string （条件必选）首帧图片 URL。约束：
string （条件必选）首帧图片 base64。约束：
string （可选）参考图类型，默认 default。 | |
inputImages array （可选）用于剧本生成和角色参考图，最多 6 张，与 firstFrameImage 相互独立。数组每项的 url 与 base64 二选一且互斥。图片约束如下：
属性 url string （条件必选）图片 URL。约束：
string （条件必选）图片 base64。约束：
string （可选）参考图类型，默认 default。 |
剧本模式（creationModel=scriptlist）
请求参数 |
|
Content-Typestring（必选）请求内容类型，固定为 application/json。 | |
Authorization string （必选）API Key 鉴权。仅支持主 API Key，以 sk- 开头，如 sk-xxx。通常配置为环境变量 $DASHSCOPE_API_KEY。临时 API Key（st- 开头）调用返回 403003。 | |
请求体（Request Body） | |
async boolean （可选）是否异步创建。默认 true：
| |
creationModel string （可选）创建子模式，剧本模式传 scriptlist。结构化剧本由您提供，服务端不再生成剧本，仅做组装并落库。World 创建后，可在 Travel 阶段调用以下控制接口：
instruct（发送文本过程指令）。各接口说明见补充说明。eventStyle 不参与 scriptlist 创建，请勿传入。 | |
refWorldId string （可选）基于已有 Directing World 衍生创建。必须是当前主账号名下的 Directing 加密 World ID；其它模型或其它主账号的 World 返回 403001。 | |
resolution string （必选）视频分辨率。可选值：
| |
firstFrameImage object （必选）直接复用为 World 首帧的图片引用。url 与 base64 二选一且互斥。图片约束如下：
属性 url string （条件必选）首帧图片 URL。约束：
string （条件必选）首帧图片 base64。约束：
string （可选）参考图类型，默认 default。 | |
scriptList object （必选）结构化剧本，必须包含 synopsis 与非空 acts。
属性 synopsis string （必选）故事梗概。非空，最长 2000 字。videoTitle string （可选）世界名称。默认 New World，最长 128 字。scene string （可选）场景设定。默认 Static Shot，最长 64 字。style string （可选）视觉风格。默认 Stable，最长 64 字。speed string （可选）叙事节奏。默认 Steady，最长 64 字。language string （可选）剧本语言。默认 en（英文），中文传 zh。最长 64 字。setting string （可选）世界观或背景设定。最长 2000 字。soundtrack string （可选）配乐描述。最长 500 字。prologue string （可选）开场白。最长 1000 字。videoTags array<string> （可选）视频标签。最多 20 个，单个标签最长 32 字。subjects array<object> （可选）预定义主体，最多 6 个。数组每项含以下属性：
subjects[] 属性 label string （可选）在 acts[].content 中引用主体。格式为 [character_x]，默认按数组顺序分配。name string （可选）人类可读名称，不渲染为画面文字。最长 64 字。type string （可选）主体类型，默认 character。决定该主体的形象与其它属性如何填写。可选值：
object （可选）主体参考图，url 与 base64 二选一且互斥，图片严格小于 6 MB。
refImage 属性 url string （条件必填）主体参考图 URL。base64 string （条件必填）主体参考图 base64。referenceType string （可选）参考图类型，默认 default。string （可选）性别描述。最长 64 字。position string （可选）画面位置。最长 64 字。ethnicity string （可选）族裔或人种描述。最长 64 字。age string （可选）年龄描述。最长 64 字。appearance string （可选）外观细节。最长 500 字。voice string （可选）音色、语速和音量描述。最长 200 字。array<object> （必选）逐拍剧本，1–45 条，全部 content 合计不超过 100000 字。数组每项含以下属性：
acts[] 属性 turn int （可选）turn 序号。1–45，不可重复，默认按数组顺序从 1 递增。content string （必选）本拍剧本。非空，单拍最长 2000 字，可用 [character_x] 引用主体。cameraType string （可选）镜头类型（镜头怎么拍）。默认 Static。可选值：
string （可选）景别，默认 Medium。决定这一拍能写多细，换景别应靠切镜，不要在同一拍里既写全身又写指尖。可选值：
cut-in 到 Close-up，再 cut-out 回宽景；多数拍用 long-take 稳住同一景别，避免景别来回跳。cut string （可选）切镜方式（这一拍怎么切进来）。默认 long-take。可选值：
|
响应参数 |
|
code integer返回码。0 表示成功，非 0 为错误码。 | |
message string错误信息。成功时为 null。 | |
data object响应数据。失败时为 null。
属性 encryptedWorldId string加密 World ID，同步 / 异步模式均返回。后续查询构建状态、World 详情和换取体验凭证均使用此值。status string当前创建状态：
stringWorld 首帧 URL；尚未生成时为 null。 |
补充说明
- 字数计算：文档中的「最长 N 字」按字符数（Unicode 字符）统计，不区分中英文——中文汉字、英文字母、数字、空格和标点符号均各算 1 个字符。
-
ScriptList 提交要求：创建 World 时
acts最多 45 条，不要求恰好 45 条；Travel 中调用 update-script 时才要求完整提交 45 条。 -
Travel 控制接口：
creationModel中列出的接口名是 World 创建后、在 Travel 阶段可调用的服务端接口，不是本接口的入参枚举值。含义如下：
错误码
如果模型调用失败并返回报错信息，请参见HappyOyster 错误码进行解决。
下一步
创建成功后可进行以下操作：
- 查询World构建状态：每 3–5 秒轮询，直到 World 进入
ready。 - World 进入
ready后，调用获取体验凭证换取一次性ticket。 - 查询World详情：查询完整创建元数据和 ScriptList。