建立一個角色演繹 World。使用自然語言 Prompt 和必填的首幀圖來建立 World，介面會立即返回加密 World ID（encryptedWorldId），World 在背景進行非同步建構，用戶端需輪詢建構進度直至完成。
適用範圍
建立一個 Acting World。呼叫前請確認下列事項：
-
驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼
403003）。- 取得主 API Key：取得與設定 API Key。
-
呼叫模式：建議使用非同步模式。
- 非同步模式（預設）：
async=true，介面立即返回encryptedWorldId，需輪詢 查詢 World 建構狀態 以獲取進度。 - 同步模式：
async=false，伺服器端內部輪詢（間隔 3s，最長 120s），建構完成後返回；若逾時則降級為非同步，由用戶端繼續輪詢。
- 非同步模式（預設）：
-
介面限制：本介面僅能建立 Acting World，無需傳入
mode（伺服器端按3寫入，若傳入非3的值則返回400000）。creationModel恆為simple，uploadMode固定為first_frame，進房版本固定為actingV2。
HTTP 呼叫
- 新加坡
- 美国（維吉尼亞）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。請求參數 |
|
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：
| |
creationModel string（選用）建立子模式。預設為 simple，Acting 僅支援 simple。 | |
prompt string （必選）角色、場景和演繹目標的自然語言描述。不可為空，最長 2000 個字元。缺失、空白或超過限制時返回 400000。 | |
uploadMode string（選用）圖片上傳模式。預設為 first_frame，Acting 僅支援 first_frame。 | |
resolution string（選用）視訊解析度。預設 480p。可選值：
| |
aspectRatio string（選用）推流畫幅，同時決定首幀圖方向，建議兩者保持一致。預設為 9:16。可選值：
9:16）建議傳入直式首幀，橫式推流（16:9）建議傳入橫式首幀。預設為 9:16，需要橫式畫面時須明確傳入 aspectRatio=16:9。 | |
refWorldId string（選用）基於現有 Acting World 衍生建立。必須是目前主帳號名下的 Acting 加密 World ID；若為其他模型或其他主帳號的 World，則返回 403001。 | |
firstFrameImage object （必選）複用作為 World 首幀的圖片引用。url 與 base64 二擇一且互斥。圖片限制條件如下：
屬性 url string（條件必選）首幀圖片 URL。與 base64 二擇一且互斥。限制條件：
string（條件必選）首幀圖片 base64。與 url 二擇一且互斥。限制條件：
string（選用）首幀參考類型。預設為 default，目前依 default 使用。 |
回應參數 |
|
code integer返回碼。0 表示成功，非 0 為錯誤碼。 | |
message string錯誤訊息。成功時為 null；失敗時為可讀的錯誤訊息。 | |
data object回應資料。失敗時為 null。
屬性 encryptedWorldId string伺服器端產生的加密 World ID。同步和非同步模式均會返回，後續輪詢建構狀態、查詢詳情、換取體驗憑證時皆使用此值。status string目前建立狀態：
stringWorld 首幀 URL；尚未生成時為 null。 |
錯誤碼
如果模型呼叫失敗並返回錯誤訊息，請參閱 HappyOyster 錯誤碼進行解決。
下一步
建立成功後可進行以下操作：
- 查詢 World 建構狀態：每 3–5 秒輪詢，直到 World 進入
ready。 - World 進入
ready後，呼叫 取得體驗憑證 以換取一次性ticket。 - 查詢 World 詳情：查詢完整的建立中繼資料。