Skip to main content

HappyOyster-Adventure-建立World API參考

建立一個世界探索 World。使用自然語言 Prompt 和必填首幀圖建立 World，介面立即返回加密 World ID，World 在背景非同步建置，用戶端輪詢建置進度直至完成。

適用範圍

建立一個 Adventure World。呼叫前請確認以下事項：
  • 驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
  • 呼叫模式：建議使用非同步模式。
    • 非同步模式（預設）：async=true，介面立即返回 encryptedWorldId，需輪詢 查詢 World 建構狀態 以獲取進度。
    • 同步模式：async=false，伺服器端內部輪詢（間隔 3s，最長 120s），建構完成後返回；若逾時則降級為非同步，由用戶端繼續輪詢。
  • 介面限制：本介面只能建立 Adventure World，無需傳 mode（服務端按 1 寫入，傳入非 1 返回 400000）。creationModel 恆為 simple，uploadMode 固定為 first_frame，進房版本固定為 wanderV2。

HTTP 呼叫

  • 新加坡
  • 华北2（北京）
  • 美国（維吉尼亞）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數

  • 首幀圖（非同步建立）
  • 首幀圖 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": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png"
    }
}'
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 stringWorld 首幀 URL；尚未生成時為 null。

錯誤碼

如果模型呼叫失敗並返回錯誤訊息，請參閱 HappyOyster 錯誤碼進行解決。

下一步

建立成功後可進行以下操作：