Skip to main content

HappyOyster-Adventure-查詢 World 詳細資料 API 參考

查詢單一 Adventure World 的完整中繼資料及可回顯的建立參數。若要輪詢建置進度，請使用查詢 World 建置狀態介面。

適用範圍

查詢單一 Adventure World 的完整中繼資料及可回顯的建立參數。呼叫前請確認下列事項：
  • 驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
  • 前置條件：使用建立 World介面返回的 encryptedWorldId 查詢。構建進度輪詢應使用查詢 World 構建狀態。
  • 呼叫方：您的伺服器端呼叫。

HTTP 呼叫

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

請求參數

  • 查詢 World 詳情
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
Authorization string （必選）API Key 驗證。僅支援主 API Key，以 sk- 開頭，如 sk-xxx。通常設定為環境變數 $DASHSCOPE_API_KEY。臨時 API Key（st- 開頭）呼叫會返回 403003。
Query 參數
encryptedWorldId string （必選）目前主帳號名下的 Adventure 加密 World ID。由建立 World介面傳回。

回應參數

  • 查詢成功
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "江南雨夜奇遇",
        "status": "ready",
        "mode": 1,
        "creationModel": "simple",
        "prompt": "黄昏的江南水乡，石桥与乌篷船",
        "eventStyle": null,
        "perspective": "third_person",
        "uploadMode": "first_frame",
        "resolution": null,
        "aspectRatio": null,
        "layout": null,
        "narrative": null,
        "refWorldId": null,
        "firstFrameImage": {
            "url": "https://cdn.happyoyster.com/frames/jiangnan.jpg",
            "referenceType": "default"
        },
        "inputImages": null,
        "sceneImage": null,
        "roleImage": null,
        "scenePrompt": null,
        "rolePrompt": null,
        "scriptList": null,
        "previewUrl": null,
        "createdAt": "2026-06-03T10:00:00Z",
        "updatedAt": "2026-06-03T10:05:00Z"
    }
}
code integer返回碼。0 表示成功，非 0 為錯誤碼。
message string錯誤訊息。成功時為 null。
data object回應資料。失敗時為 null。

屬性

encryptedWorldId string加密 World ID。name stringWorld 名稱。status string構建狀態：generating / ready / failed。mode integerAdventure 恆為 1。creationModel stringAdventure 恆為 simple。prompt string建立時提交的頂層 Prompt。eventStyle nullAdventure 不使用此建立參數，通常為 null。此欄位僅在 Directing creationModel=simple 時生效。perspective string視角：first_person / third_person。uploadMode string固定為 first_frame。resolution nullAdventure 不使用此欄位，通常為 null。aspectRatio nullAdventure 不使用此欄位，固定為 null。layout nullAdventure 不使用此欄位，通常為 null。narrative nullAdventure 不使用此欄位，通常為 null。refWorldId string衍生建立時使用的加密參考 World ID；若無則為 null。firstFrameImage object建立時的必填首幀圖片；只返回 URL 形式。含 url 和 referenceType。inputImages nullAdventure 目前不使用此欄位。scriptList nullAdventure 不支援 ScriptList，固定為 null。previewUrl null目前固定為 null。createdAt string建立時間，ISO 8601 格式。updatedAt string最近更新時間，ISO 8601 格式。

前置狀態與呼叫注意事項

  • 本介面可查詢 generating、ready 或 failed World；部分構建產物在未就緒時可能為 null。
  • 詳情介面不回顯 async，因為它是呼叫行為開關，不是 World 屬性。
  • 圖片只返回 URL 和 referenceType，不會回傳建立請求中的 base64 內容。
  • 查詢其他模型、其他主帳號或已刪除的 World 均會傳回 403001，不會洩漏資源是否存在。

錯誤碼

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

下一步