创建一个角色演绎 World。使用自然语言 Prompt 和必填首帧图创建 World，接口立即返回加密 World ID（encryptedWorldId），World 在后台异步构建，客户端轮询构建进度直至完成。
适用范围
创建一个 Acting World。调用前请确认以下事项：
-
鉴权要求：仅支持主 API Key调用，临时 API Key 不可用（错误码
403003）。- 获取主 API Key：获取与配置 API Key。
-
调用模式：推荐使用异步模式。
- 异步模式（默认）：
async=true，接口立即返回encryptedWorldId，需轮询查询World构建状态获取进度。 - 同步模式：
async=false，服务端内部轮询（间隔 3s，最长 120s），构建完成后返回；超时则降级为异步，客户端继续轮询。
- 异步模式（默认）：
-
接口限制：本接口只能创建 Acting World，无需传
mode（服务端按3写入，传入非3返回400000）。creationModel恒为simple，uploadMode固定为first_frame，进房版本固定为actingV2。
HTTP调用
- 新加坡
- 美国（弗吉尼亚）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds调用时请将{WorkspaceId}替换为真实的Workspace ID。请求参数 |
|
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，Acting 仅支持 simple。 | |
prompt string （必选）角色、场景和演绎目标的自然语言描述。非空，最长 2000 字符。缺失、空白或超限返回 400000。 | |
uploadMode string （可选）图片上传模式。默认 first_frame，Acting 仅支持 first_frame。 | |
resolution string （可选）视频分辨率。默认 480p。可选值：
| |
aspectRatio string （可选）推流画幅，同时决定首帧图方向，建议两者保持一致。默认 9:16。可选值：
9:16）建议传竖屏首帧，横屏推流（16:9）建议传横屏首帧。默认 9:16，需要横屏时须显式传入 aspectRatio=16:9。 | |
refWorldId string （可选）基于已有 Acting World 衍生创建。必须是当前主账号名下的 Acting 加密 World ID；其它模型或其它主账号的 World 返回 403001。 | |
firstFrameImage object （必选）复用为 World 首帧的图片引用。url 与 base64 二选一且互斥。图片约束如下：
属性 url string （条件必选）首帧图片 URL。与 base64 二选一且互斥。约束：
string （条件必选）首帧图片 base64。与 url 二选一且互斥。约束：
string （可选）首帧参考类型。默认 default，当前按 default 使用。 |
响应参数 |
|
code integer返回码。0 表示成功，非 0 为错误码。 | |
message string错误信息。成功时为 null；失败时为可读错误信息。 | |
data object响应数据。失败时为 null。
属性 encryptedWorldId string服务端生成的加密 World ID。同步和异步模式均返回，后续构建状态轮询、详情查询、换取体验凭证均使用此值。status string当前创建状态：
stringWorld 首帧 URL；尚未生成时为 null。 |
错误码
如果模型调用失败并返回报错信息，请参见HappyOyster 错误码进行解决。
下一步
创建成功后可进行以下操作：
- 查询World构建状态：每 3–5 秒轮询，直到 World 进入
ready。 - World 进入
ready后，调用获取体验凭证换取一次性ticket。 - 查询World详情：查询完整创建元数据。