Skip to main content

HappyOyster-Acting-查詢 World 詳情 API 參考

查詢單個 Acting World 的完整中繼資料和可回顯建立參數。構建進度輪詢請使用查詢 World 構建狀態介面。

適用範圍

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

HTTP 呼叫

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

請求參數

  • 查詢 World 詳情
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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 （必選）目前主帳號名下的 Acting 加密 World ID。由建立 World介面返回。

回應參數

查询成功
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "深夜视频通话",
        "status": "ready",
        "mode": 3,
        "creationModel": "simple",
        "prompt": "深夜视频通话中，一位安静的女孩微笑着回应镜头",
        "eventStyle": "first_frame",
        "perspective": null,
        "uploadMode": "first_frame",
        "resolution": "480p",
        "aspectRatio": "9:16",
        "layout": null,
        "narrative": null,
        "refWorldId": null,
        "firstFrameImage": {
            "url": "https://cdn.happyoyster.com/frames/portrait-call.jpg",
            "referenceType": "default"
        },
        "inputImages": null,
        "sceneImage": null,
        "roleImage": null,
        "scenePrompt": null,
        "rolePrompt": null,
        "scriptList": null,
        "previewUrl": null,
        "createdAt": "2026-09-09T08:00:00Z",
        "updatedAt": "2026-09-09T08:05:00Z"
    }
}
code integer返回碼。0 表示成功，非 0 為錯誤碼。
message string錯誤訊息。成功時為 null。
data object回應資料。失敗時為 null。

屬性

encryptedWorldId string加密 World ID。name stringWorld 名稱。status string構建狀態：generating / ready / failed。mode integerActing 恆為 3。creationModel stringActing 恆為 simple。prompt string建立時提交的頂層 Prompt。eventStyle string相容返回欄位；合規建立省略該欄位時，伺服器端通常按 uploadMode 映射並回顯 first_frame。它不是 Acting 的建立參數，用戶端不應主動回傳。perspective nullActing 不接受視角建立參數，固定為 null。uploadMode string固定為 first_frame。resolution string480p / 720p；建立時未傳則為 480p。aspectRatio string9:16 / 16:9；建立時未傳則為 9:16。layout nullActing 不接受該建立參數，固定為 null。narrative nullActing 不接受該建立參數，固定為 null。refWorldId string衍生建立時使用的 Acting 加密參考 World ID；無則為 null。firstFrameImage object建立時的必填首幀圖；只返回 URL 形式，不回傳 base64。含 url 和 referenceType。inputImages nullActing 目前不使用該欄位。sceneImage nullActing 不使用場景角色圖片欄位，固定為 null。roleImage nullActing 不使用場景角色圖片欄位，固定為 null。scenePrompt nullActing 不使用場景角色文案，固定為 null。rolePrompt nullActing 不使用場景角色文案，固定為 null。scriptList nullActing 不支援 ScriptList，固定為 null。previewUrl null目前固定為 null。createdAt string建立時間，ISO 8601 格式。updatedAt string最近更新時間，ISO 8601 格式。

前置狀態與呼叫注意事項

  • 本介面可查詢 generating、ready 或 failed World；部分構建產物在未就緒時可能為 null。
  • 詳情介面不回顯 async，因為它是呼叫行為開關，不是 World 屬性。
  • 圖片只返回 URL 和 referenceType，不會回傳建立請求中的 base64 內容。
  • eventStyle 通常與 uploadMode 同值；用戶端應以 uploadMode 作為 Acting 建立模式的權威欄位。
  • 播放器可預先讀取 aspectRatio，但實際進房時仍應以進入房間回應值設定方向。
  • 查詢其它模型、其它主帳號或已刪除的 World 均返回 403001，不會洩漏資源是否存在。

錯誤碼

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

下一步