跳转到主要内容
千问AI平台 home page
文档
Adventure

HappyOyster-Adventure-创建World API参考

创建一个世界探索 World。使用自然语言 Prompt 和必填首帧图创建 World，接口立即返回加密 World ID，World 在后台异步构建，客户端轮询构建进度直至完成。

POST
/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
curl --location 'https://maas.qianwenaiapi.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": "第三人称跟拍：一名身穿黑色防寒服、头戴黑色头盔的骑手骑着黑色雪地摩托驶向远方，履带扬起细雪。前方是积雪覆盖的针叶林，更远处是日照岩壁的陡峭雪山与蓝天白云。冬日晴空，雪地高光强烈，开阔冷冽。",
  "eventStyle": "dramatic",
  "firstFrameImage": {
    "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png",
    "referenceType": "default"
  }
}'
{
  "code": 0,
  "message": null,
  "data": {
    "encryptedWorldId": "enc_a1b2****",
    "status": "generating",
    "firstFrame": null
  }
}

适用范围

创建一个 Adventure World。调用前请确认：
  • 仅支持主 API Key调用，临时 API Key 不可用（错误码 403003）。
  • 推荐使用异步模式：async=true，接口立即返回 encryptedWorldId，需轮询查询World构建状态获取进度。
  • 本接口只能创建 Adventure World，无需传 mode；creationModel 恒为 simple，uploadMode 固定为 first_frame。
调用失败时，请参见HappyOyster 错误码。

鉴权

​
string
header
必填

千问AI平台 API Key。仅支持主 API Key（sk- 开头）。详见获取 API Key。

Header 参数

​
string
默认值"application/json"
必填

请求内容类型。此参数必须设置为 application/json。

​
string
必填

API Key 鉴权。仅支持主 API Key，以 sk- 开头，如 sk-xxx。通常配置为环境变量 $DASHSCOPE_API_KEY。临时 API Key（st- 开头）调用返回 403003。

请求体

application/json
​
enum<string>
必填

视角。缺少该字段返回 400000。

可选值：first_person,third_person
​
string
必填

世界主题描述，支持中英文。非空，最长 2000 字符。缺失、空白或超限返回 400000。

​
object
必填

直接复用为 World 首帧的图片引用。url 与 base64 二选一且互斥。图片约束：格式 JPG/JPEG/PNG/WebP；单张严格小于 6 MB；宽高比必须为横屏，宽/高为 1.5-2.0；未通过内容安全或版权/IP 校验返回 403004/403005。

​
boolean
默认值true

是否异步创建。默认 true。true：立即返回，World 在后台构建，客户端轮询查询World构建状态；false：服务端每 3 秒轮询一次，最长等待 120 秒，构建完成后返回，超时仍返回 generating，客户端随后改为自行轮询。

​
enum<string>
默认值"simple"

创建子模式。默认 simple，Adventure 仅支持 simple。

可选值：simple
​
enum<string>
默认值"first_frame"

图片上传模式。默认 first_frame，Adventure 仅支持 first_frame。

可选值：first_frame
​
enum<string>
默认值"normal"

事件风格，用于选择剧本生成模板。默认 normal。normal：常规/标准风格（默认），按用户意图补全 4-5 幕，节奏相对平稳；dramatic：戏剧/冲突风格，按约 180 秒三幕骨架生成剧本；regular：旧值，等同 normal，仅用于兼容历史入参，新调用请勿再使用。

可选值：normal,dramatic,regular
​
string

基于已有 Adventure World 衍生创建。必须是当前千问AI平台账号名下的 Adventure 加密 World ID；其它模型或其它千问AI平台账号的 World 返回 403001。

响应

200-application/json
​
integer

返回码。0 表示成功，非 0 为错误码。

​
string

错误信息。成功时为 null。

​
object

响应数据。失败时为 null。