建立一個即時導演 World。支援普通模式（自然語言 Prompt）和劇本模式（結構化 ScriptList），介面立即返回加密 World ID，World 在後台非同步建構，用戶端輪詢建構進度直至完成。
適用範圍
建立一個 Directing World。呼叫前請確認以下事項：
-
驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼
403003）。- 取得主 API Key：取得與設定 API Key。
-
呼叫模式：建議使用非同步模式。
- 非同步模式（預設）：
async=true，介面立即返回encryptedWorldId，需輪詢 查詢 World 建構狀態 以獲取進度。 - 同步模式：
async=false，伺服器端內部輪詢（間隔 3s，最長 120s），建構完成後返回；若逾時則降級為非同步，由用戶端繼續輪詢。
- 非同步模式（預設）：
-
介面限制：本介面僅能建立 Directing World，無需傳入
mode（伺服器端按2寫入，若傳入非2則返回400000）。creationModel支援simple（普通模式，預設）與scriptlist（劇本模式），進房版本固定為storyV2，aspectRatio與maxExperienceTimeSec固定為null。
HTTP 呼叫
- 新加坡
- 美国（維吉尼亞）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。普通模式（creationModel=simple）
請求參數 |
|
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（預設）。由您提供自然語言 prompt，伺服器端產生完整的 45 拍劇本、首幀（可自行攜帶）及角色參考圖。World 建立後，可在 Travel 階段呼叫以下控制介面：
| |
eventStyle string （可選）僅當 creationModel=simple 時生效：選擇劇本產生範本。預設為 normal。可選值：
| |
refWorldId string （可選）基於現有 Directing World 衍生建立。必須是目前主帳號名下的 Directing 加密 World ID；若為其他模型或其他主帳號的 World，則返回 403001。 | |
prompt string （必選）世界主題描述，支援中英文。非空，最長 2000 字元。 | |
resolution string （必選）影片解析度。可選值：
| |
layout string （可選）鏡頭運動風格（鏡頭怎麼動、切得多猛）。可選值：
| |
narrative string （可選）敘事風格（戲密不密、情緒強不強）。可選值：
| |
firstFrameImage object （可選）提供後直接複用作為 World 首幀，跳過 AI 首幀產生步驟。url 與 base64 二擇一且互斥。圖片限制如下：
屬性 url string （條件必選）首幀圖片 URL。限制條件：
string （條件必選）首幀圖片 base64。限制條件：
string （可選）參考圖類型，預設 default。 | |
inputImages array （可選）用於劇本產生與角色參考圖，最多 6 張，與 firstFrameImage 相互獨立。陣列中每個項目的 url 與 base64 二擇一且互斥。圖片限制如下：
屬性 url string （條件必選）圖片 URL。限制條件：
string （條件必選）圖片 base64。限制條件：
string （可選）參考圖類型，預設 default。 |
劇本模式（creationModel=scriptlist）
請求參數 |
|
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 （可選）建立子模式，劇本模式請傳入 scriptlist。結構化劇本由您提供，伺服器端不再產生劇本，僅進行組裝並存入資料庫。World 建立後，可在 Travel 階段呼叫以下控制介面：
instruct（傳送文字過程指令）。各介面說明請參閱補充說明。eventStyle 不參與 scriptlist 建立，請勿傳入。 | |
refWorldId string （可選）基於現有 Directing World 衍生建立。必須是目前主帳號名下的 Directing 加密 World ID；若為其他模型或其他主帳號的 World，則返回 403001。 | |
resolution string （必選）影片解析度。可選值：
| |
firstFrameImage object （必選）直接複用為 World 首幀的圖片引用。url 與 base64 二選一且互斥。圖片約束如下：
屬性 url string （條件必選）首幀圖片 URL。限制條件：
string （條件必選）首幀圖片 base64。限制條件：
string （可選）參考圖類型，預設 default。 | |
scriptList object （必選）結構化劇本，必須包含 synopsis 與非空的 acts。
屬性 synopsis string （必選）故事梗概。非空，最長 2000 字。videoTitle string （可選）世界名稱。預設為 New World，最長 128 個字元。scene string （可選）場景設定。預設為 Static Shot，最長 64 個字元。style string （可選）視覺風格。預設 Stable，最長 64 字。speed string （可選）敘事節奏。預設 Steady，最長 64 字。language string （可選）劇本語言。預設為 en（英文），中文請傳入 zh。最長 64 個字元。setting string （可選）世界觀或背景設定。最長 2000 字。soundtrack string （可選）配樂描述。最長 500 字。prologue string （可選）開場白。最長 1000 字。videoTags array<string> （可選）影片標籤。最多 20 個，單個標籤最長 32 字。subjects array<object> （可選）預定義主體，最多 6 個。陣列每項含以下屬性：
subjects[] 屬性 label string （可選）在 acts[].content 中引用主體。格式為 [character_x]，預設依陣列順序分配。name string （可選）人類可讀名稱，不渲染為畫面文字。最長 64 字。type string （可選）主體類型，預設為 character。決定該主體的形象與其他屬性填寫方式。可選值：
object （可選）主體參考圖，url 與 base64 二擇一且互斥，圖片大小須嚴格小於 6 MB。
refImage 屬性 url string （條件必填）主體參考圖 URL。base64 string （條件必填）主體參考圖 base64。referenceType string （可選）參考圖類型，預設 default。string （可選）性別描述。最長 64 字。position string （可選）畫面位置。最長 64 字。ethnicity string （可選）族裔或人種描述。最長 64 字。age string （可選）年齡描述。最長 64 字。appearance string （可選）外觀細節。最長 500 字。voice string （可選）音色、語速和音量描述。最長 200 字。array<object> （必選）逐拍劇本，1–45 條，所有 content 合計不超過 100000 個字元。陣列中每個項目包含以下屬性：
acts[] 屬性 turn int （可選）turn 序號。1–45，不可重複，預設依陣列順序從 1 遞增。content string （必選）本拍劇本。不可為空，單拍最長 2000 個字元，可使用 [character_x] 引用主體。cameraType string （可選）鏡頭類型（鏡頭怎麼拍）。預設 Static。可選值：
string （可選）景別，預設為 Medium。決定此拍可描寫的細緻程度，更換景別應透過切鏡進行，避免在同一拍中同時描寫全身與指尖。可選值：
cut-in 至 Close-up，再 cut-out 回到寬景；多數鏡頭使用 long-take 維持同一景別，避免景別反覆跳動。cut string （可選）切鏡方式（此拍如何切入）。預設為 long-take。可選值：
|
回應參數 |
|
code integer返回碼。0 表示成功，非 0 為錯誤碼。 | |
message string錯誤訊息。成功時為 null。 | |
data object回應資料。失敗時為 null。
屬性 encryptedWorldId string加密 World ID，同步與非同步模式皆會返回。後續查詢建構狀態、World 詳情及換取體驗憑證時均使用此值。status string目前建立狀態：
stringWorld 首幀 URL；尚未生成時為 null。 |
補充說明
- 字數計算：文件中的「最長 N 字」依字元數（Unicode 字元）統計，不區分中英文——中文漢字、英文字母、數字、空格和標點符號均各算 1 個字元。
-
ScriptList 提交要求：建立 World 時
acts最多 45 條，不要求恰好 45 條；在 Travel 中呼叫 update-script 時才要求完整提交 45 條。 -
Travel 控制介面：
creationModel中列出的介面名稱是 World 建立後、在 Travel 階段可呼叫的伺服器端介面，並非本介面的輸入參數枚舉值。含義如下：
錯誤碼
如果模型呼叫失敗並返回錯誤訊息，請參閱 HappyOyster 錯誤碼進行解決。
下一步
建立成功後可進行以下操作：
- 查詢 World 建構狀態：每 3–5 秒輪詢，直到 World 進入
ready。 - World 進入
ready後，呼叫 取得體驗憑證 以換取一次性ticket。 - 查詢 World 詳情：查詢完整的建立中繼資料與 ScriptList。