HappyOyster-Directing-建立World API參考 - Alibaba Cloud Model Studio

建立一個即時導演 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。

美国（維吉尼亞）

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

普通模式（`creationModel=simple`）

請求參數

普通模式·純文字（非同步建立）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "第一视角（POV）互动视频，镜头模拟我的双眼，锁定正对面的白色马尔济斯小狗：白色厨师帽、黑色扣子厨师服。柔和居家厨房背景，光影温暖，小狗眼神始终看向镜头。",
    "resolution": "720p",
    "layout": "Stable",
    "narrative": "Calm"
}'

普通模式·文字+參考圖（非同步建立）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "窗边咖啡馆。黑长发年轻女子穿米色高领毛衣侧坐，左手托腮望向布满雨珠的玻璃窗。木桌上有一杯冒热气的深色咖啡。窗外雨夜暖黄街灯，室内一盏吊灯。安静雨夜。",
    "resolution": "720p",
    "inputImages": [
        {
            "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
            "referenceType": "default"
        }
    ]
}'

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，用戶端隨後改為自行輪詢。

creationModel string （可選）

建立子模式，普通模式請傳入 simple（預設）。由您提供自然語言 prompt，伺服器端產生完整的 45 拍劇本、首幀（可自行攜帶）及角色參考圖。World 建立後，可在 Travel 階段呼叫以下控制介面：

instruct：傳送文字過程指令
pause：暫停
resume：恢復
rewind：回溯
end：結束

各介面說明請參閱補充說明。

eventStyle string （可選）

僅當 creationModel=simple 時生效：選擇劇本產生範本。預設為 normal。可選值：

normal：常規／標準風格（預設）。依使用者意圖補全 4–5 幕，節奏相對平穩，不強行加入衝突、反轉或三幕高潮。
dramatic：戲劇／衝突風格。依約 180 秒的三幕骨架產生劇本：開場鉤子、上升衝突、轉折、高潮收束；開放演繹時依類型安排反轉（懸疑／驚悚／逆襲等），節奏更密、戲劇性更強。
regular：舊值，僅為相容歷史輸入參數而保留，伺服器端將按 normal 處理；新呼叫請勿使用。

refWorldId string （可選）

基於現有 Directing World 衍生建立。必須是目前主帳號名下的 Directing 加密 World ID；若為其他模型或其他主帳號的 World，則返回 403001。

prompt string （必選）

世界主題描述，支援中英文。非空，最長 2000 字元。

resolution string （必選）

影片解析度。可選值：

480p
720p

layout string （可選）

鏡頭運動風格（鏡頭怎麼動、切得多猛）。可選值：

Stable：鏡頭穩、運動少，偏連續長鏡頭，切鏡稀疏
Fast：鏡頭快、動能強，硬切／快速變焦／景別跳變更密集
Calm：介於兩者之間，鏡頭克制，不急不猛

narrative string （可選）

敘事風格（戲密不密、情緒強不強）。可選值：

Calm：事件少，偏氛圍、慢推進
Dramatic：事件密集，反應／反轉／障礙更明顯，張力高
Normal：常規敘事密度，中間檔
Steady：節奏均勻、不堆疊高潮，與 Normal 接近

firstFrameImage object （可選）

提供後直接複用作為 World 首幀，跳過 AI 首幀產生步驟。url 與 base64 二擇一且互斥。圖片限制如下：

格式：JPG / JPEG / PNG / WebP
大小：單張嚴格小於 6 MB
寬高比：必須為橫向，寬 / 高為 1.5–2.0（畫面比例跟隨該圖）
內容安全：未通過內容安全或版權 / IP 驗證時返回 403004 / 403005

屬性

url string （條件必選）

首幀圖片 URL。限制條件：

必須是帶有 Host 的合法 http / https URL，並可由伺服器端存取
真實格式、大小和首幀寬高比在轉存後校驗
非同步請求可能先返回 generating，隨後 World 因圖片驗證失敗而進入 failed

base64 string （條件必選）

首幀圖片 base64。限制條件：

建議使用完整的 data URI data:image/<subtype>;base64,<payload>
在建立入口同步校驗格式、大小和首幀寬高比

referenceType string （可選）

參考圖類型，預設 default。

inputImages array （可選）

用於劇本產生與角色參考圖，最多 6 張，與 firstFrameImage 相互獨立。陣列中每個項目的 url 與 base64 二擇一且互斥。圖片限制如下：

格式：JPG / JPEG / PNG / WebP
大小：單張嚴格小於 6 MB
寬高比：必須為橫向，寬 / 高為 1.5–2.0（畫面比例跟隨該圖）
內容安全：未通過內容安全或版權 / IP 驗證時返回 403004 / 403005

屬性

url string （條件必選）

圖片 URL。限制條件：

必須是帶有 Host 的合法 http / https URL，並可由伺服器端存取
真實格式、大小和寬高比在轉存後驗證
非同步請求可能先返回 generating，隨後 World 因圖片驗證失敗而進入 failed

base64 string （條件必選）

圖片 base64。限制條件：

建議使用完整的 data URI data:image/<subtype>;base64,<payload>
在建立入口同步驗證格式、大小和寬高比

referenceType string （可選）

參考圖類型，預設 default。

劇本模式（`creationModel=scriptlist`）

請求參數

劇本模式（非同步建立）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "scriptlist",
    "resolution": "720p",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
        "referenceType": "default"
    },
    "scriptList": {
        "videoTitle": "苏念·今晚陪你坐一会儿",
        "synopsis": "少女苏念坐在浅色书桌前正对镜头，陪你慢慢聊天、把今天放下。",
        "subjects": [
            {
                "label": "[character_1]",
                "name": "苏念",
                "type": "character",
                "gender": "female",
                "age": "少女",
                "ethnicity": "东亚",
                "appearance": "黑色中长直发偏分，圆润脸型，米白色针织上衣，二次元动漫风，干净线条",
                "position": "画面中央，坐在浅色书桌前",
                "voice": "温柔少女声，语速偏慢，音量适中"
            }
        ],
        "acts": [
            {
                "turn": 1,
                "content": "[character_1] 坐在浅色书桌前正对镜头，身体微微前倾，眼睛弯起轻声说「来啦，今晚也陪你坐一会儿，慢慢聊」",
                "cameraType": "Push-in",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] 双手交叠放在桌上，轻轻点头说「先把今天那些烦心的事，都暂时放到一边吧」",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 3,
                "content": "[character_1] 微微歪头，表情温和地看着镜头，问「这一天过下来，你还好吗，累不累」",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            }
        ]
    }
}'

Content-Typestring（必選）

請求內容類型，固定為 application/json。

Authorization string （必選）

請求主體（Request Body）

async boolean （可選）

是否非同步建立。預設 true：

true：立即返回，World 在背景建構，用戶端輪詢查詢 World 建構狀態。
false：伺服器端每 3 秒輪詢一次，最長等待 120 秒，建構完成後返回；若逾時仍返回 generating，用戶端隨後改為自行輪詢。

creationModel string （可選）

建立子模式，劇本模式請傳入 scriptlist。結構化劇本由您提供，伺服器端不再產生劇本，僅進行組裝並存入資料庫。World 建立後，可在 Travel 階段呼叫以下控制介面：

update-script：全量替換劇本
pause：暫停
resume：恢復
rewind：回溯
end：結束

不支援 instruct（傳送文字過程指令）。各介面說明請參閱補充說明。

說明

eventStyle 不參與 scriptlist 建立，請勿傳入。

refWorldId string （可選）

基於現有 Directing World 衍生建立。必須是目前主帳號名下的 Directing 加密 World ID；若為其他模型或其他主帳號的 World，則返回 403001。

resolution string （必選）

影片解析度。可選值：

480p
720p

firstFrameImage object （必選）

直接複用為 World 首幀的圖片引用。url 與 base64 二選一且互斥。圖片約束如下：

格式：JPG / JPEG / PNG / WebP
大小：單張嚴格小於 6 MB
寬高比：必須為橫向，寬 / 高為 1.5–2.0（畫面比例跟隨該圖）
內容安全：未通過內容安全或版權 / IP 驗證時返回 403004 / 403005

屬性

url string （條件必選）

首幀圖片 URL。限制條件：

必須是帶有 Host 的合法 http / https URL，並可由伺服器端存取
真實格式、大小和首幀寬高比在轉存後校驗
非同步請求可能先返回 generating，隨後 World 因圖片驗證失敗而進入 failed

base64 string （條件必選）

首幀圖片 base64。限制條件：

建議使用完整的 data URI data:image/<subtype>;base64,<payload>
在建立入口同步校驗格式、大小和首幀寬高比

referenceType 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。決定該主體的形象與其他屬性填寫方式。可選值：

character：人類角色（預設）。依人物填寫 gender／position／ethnicity／age／appearance。
animal：真實動物（貓、狗、馬等）。以物種取代性別、亞種／品種取代族裔。
creature：非人／幻想生物（龍、妖怪、外星人等）。同樣依非人形象填寫。
narrator：旁白／畫外音。仅有聲音、無畫面，需填寫 voice，不會產出參考圖。

refImage object （可選）

主體參考圖，url 與 base64 二擇一且互斥，圖片大小須嚴格小於 6 MB。

refImage 屬性

url string （條件必填）

主體參考圖 URL。

base64 string （條件必填）

主體參考圖 base64。

referenceType string （可選）

參考圖類型，預設 default。

gender string （可選）

性別描述。最長 64 字。

position string （可選）

畫面位置。最長 64 字。

ethnicity string （可選）

族裔或人種描述。最長 64 字。

age string （可選）

年齡描述。最長 64 字。

appearance string （可選）

外觀細節。最長 500 字。

voice string （可選）

音色、語速和音量描述。最長 200 字。

acts array<object> （必選）

逐拍劇本，1–45 條，所有 content 合計不超過 100000 個字元。陣列中每個項目包含以下屬性：

acts[] 屬性

turn int （可選）

turn 序號。1–45，不可重複，預設依陣列順序從 1 遞增。

content string （必選）

本拍劇本。不可為空，單拍最長 2000 個字元，可使用 [character_x] 引用主體。

cameraType string （可選）

鏡頭類型（鏡頭怎麼拍）。預設 Static。可選值：

Static：機位鎖定，不推不搖（預設值）。景別透過 shotSize 控制：遠／中／近
Tracking：跟拍。機位跟著主體走，保持跟拍距離
Pan Left：機位不動，鏡頭向左橫搖
Pan Right：機位不動，鏡頭向右橫搖
Tilt Up：鏡頭上仰
Tilt Down：鏡頭下俯
Push-in：光學 / 物理推進，畫面逐漸靠近
Pull-out：拉遠，畫面逐漸變寬
POV Forward：第一人稱，鏡頭即眼睛，向前走
POV Look Down：第一人稱低頭看
POV Look Up：第一人稱抬頭看
POV Turn Left：第一人稱左轉看
POV Turn Right：第一人稱右轉看

shotSize string （可選）

景別，預設為 Medium。決定此拍可描寫的細緻程度，更換景別應透過切鏡進行，避免在同一拍中同時描寫全身與指尖。可選值：

Wide：遠景／全景，包含全身與環境關係。適合走位、站位、空間調度，不描寫微表情或指尖細節。
Medium：中景（預設），上半身姿態與手勢。適合對話與日常動作，不描寫腳部走位或精細手部操作。
Close-up：特寫，一張臉／一隻手／一件道具。適合表現表情與關鍵細節，不描寫全身移動。

與切鏡搭配：若要觀察更細微處，先 cut-in 至 Close-up，再 cut-out 回到寬景；多數鏡頭使用 long-take 維持同一景別，避免景別反覆跳動。

cut string （可選）

切鏡方式（此拍如何切入）。預設為 long-take。可選值：

long-take：不切換，接續上一鏡頭拍攝。預設值，也最穩定
hard-cut：硬切，瞬間切換至另一鏡頭。適用於對話正反打
cut-in：切至較近的景別，例如 Medium → Close-up。用於查看細節或接手部互動
cut-out：切至較遠的景別，例如 Close-up → Medium／Wide
cutaway：短暫切到主線之外的細節
cutback：從 cutaway 切回主主體。僅能接在 cutaway 之後
camera movement transition：以快速運鏡連接兩段，而非硬切

回應參數

非同步建立

{
    "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，同步與非同步模式皆會返回。後續查詢建構狀態、World 詳情及換取體驗憑證時均使用此值。

status string

目前建立狀態：

generating：建立中
ready：就緒
failed：建立失敗

firstFrame string

World 首幀 URL；尚未生成時為 null。

補充說明

字數計算：文件中的「最長 N 字」依字元數（Unicode 字元）統計，不區分中英文——中文漢字、英文字母、數字、空格和標點符號均各算 1 個字元。
ScriptList 提交要求：建立 World 時 acts 最多 45 條，不要求恰好 45 條；在 Travel 中呼叫 update-script 時才要求完整提交 45 條。
Travel 控制介面：creationModel 中列出的介面名稱是 World 建立後、在 Travel 階段可呼叫的伺服器端介面，並非本介面的輸入參數枚舉值。含義如下：
- instruct：向執行中的 Travel 傳送文字過程指令，僅限普通模式。
- pause：暫停 Travel。
- resume：恢復播放。
- rewind：回溯至指定時間點，需先暫停。
- end：結束 Travel。
- update-script：全量替換劇本，僅限劇本模式。

錯誤碼

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

下一步

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

查詢 World 建構狀態：每 3–5 秒輪詢，直到 World 進入 ready。
World 進入 ready 後，呼叫取得體驗憑證以換取一次性 ticket。
查詢 World 詳情：查詢完整的建立中繼資料與 ScriptList。

適用範圍

HTTP 呼叫

新加坡

美国（維吉尼亞）

普通模式（creationModel=simple）

請求參數

普通模式·純文字（非同步建立）

普通模式·文字+參考圖（非同步建立）

請求主體（Request Body）

劇本模式（creationModel=scriptlist）

請求參數

劇本模式（非同步建立）

請求主體（Request Body）

回應參數

非同步建立

補充說明

錯誤碼

下一步

普通模式（`creationModel=simple`）

劇本模式（`creationModel=scriptlist`）