创建一个世界探索 World。使用自然语言 Prompt 和必填首帧图创建 World，接口立即返回加密 World ID，World 在后台异步构建，客户端轮询构建进度直至完成。
适用范围
创建一个 Adventure World。调用前请确认以下事项：
HTTP调用
新加坡
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
调用时请将{WorkspaceId}替换为真实的Workspace ID。
华北2（北京）
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
调用时请将{WorkspaceId}替换为真实的Workspace ID。
美国（弗吉尼亚）
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
调用时请将{WorkspaceId}替换为真实的Workspace ID。
请求参数 | 首帧图（异步创建）curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"perspective": "third_person",
"prompt": "第三人称跟拍：一名身穿黑色防寒服、头戴黑色头盔的骑手骑着黑色雪地摩托驶向远方，履带扬起细雪。前方是积雪覆盖的针叶林，更远处是日照岩壁的陡峭雪山与蓝天白云。冬日晴空，雪地高光强烈，开阔冷冽。",
"firstFrameImage": {
"url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png"
}
}'
首帧图base64（异步创建）curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"perspective": "third_person",
"prompt": "第三人称跟拍：一名身穿黑色防寒服、头戴黑色头盔的骑手骑着黑色雪地摩托驶向远方，履带扬起细雪。前方是积雪覆盖的针叶林，更远处是日照岩壁的陡峭雪山与蓝天白云。冬日晴空，雪地高光强烈，开阔冷冽。",
"firstFrameImage": {
"base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
}'
|
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：
true：立即返回，World 在后台构建，客户端轮询查询World构建状态。false：服务端每 3 秒轮询一次，最长等待 120 秒，构建完成后返回；超时仍返回 generating，客户端随后改为自行轮询。 |
perspective string （必选） 视角。可选值：
first_person：第一人称third_person：第三人称 缺少该字段返回 400000。 |
prompt string （必选） 世界主题描述，支持中英文。非空，最长 2000 字符。缺失、空白或超限返回 400000。 |
creationModel string （可选） 创建子模式。默认 simple，Adventure 仅支持 simple。 |
uploadMode string （可选） 图片上传模式。默认 first_frame，Adventure 仅支持 first_frame。 |
refWorldId string （可选） 基于已有 Adventure World 衍生创建。必须是当前主账号名下的 Adventure 加密 World ID；其它模型或其它主账号的 World 返回 403001。 |
firstFrameImage object （必选） 直接复用为 World 首帧的图片引用。url 与 base64 二选一且互斥。图片约束如下：
- 格式：JPG / JPEG / PNG / WebP
- 大小：单张严格小于 6 MB
- 宽高比：必须为横屏，宽 / 高为 1.5–2.0（画面比例跟随该图）
- 内容安全：未通过内容安全或版权 / IP 校验返回
403004 / 403005
属性 url string （条件必选） 首帧图片 URL。与 base64 二选一且互斥。约束：
- 必须是带 Host 的合法
http / https URL，并可由服务端访问
- 真实格式、大小和首帧宽高比在转存后校验
- 异步请求可能先返回
generating，随后 World 因图片校验失败进入 failed
base64 string （条件必选） 首帧图片 base64。与 url 二选一且互斥。约束：
- 推荐使用完整 data URI
data:image/<subtype>;base64,<payload>
- 在创建入口同步校验格式、大小和首帧宽高比
referenceType string （可选） 参考图类型。默认 default，当前按 default 使用。 |
响应参数 | 异步创建{
"code": 0,
"message": null,
"data": {
"encryptedWorldId": "enc_a1b2****",
"status": "generating",
"firstFrame": null
}
}
|
code integer 返回码。0 表示成功，非 0 为错误码。 |
message string 错误信息。成功时为 null。 |
data object 响应数据。失败时为 null。 属性 encryptedWorldId string 服务端生成的加密 World ID。同步和异步模式均返回，后续构建状态轮询、详情查询、换取体验凭证均使用此值。 status string 当前创建状态：generating（构建中）或 ready（就绪）；同步构建失败时也可能为 failed。 firstFrame string World 首帧 URL；尚未生成时为 null。 |
错误码
如果模型调用失败并返回报错信息，请参见HappyOyster 错误码进行解决。
下一步
创建成功后可进行以下操作：