HappyOyster-Directing-劇本全量更新 API參考 - Alibaba Cloud Model Studio

在劇本模式 Travel 中提交完整的 45 個 turn，全量替換當前 Travel 的 acts。僅 creationModel=scriptlist 支援。

適用範圍

在劇本模式（creationModel=scriptlist）Travel 中提交完整的 45 個 turn，全量替換當前 Travel 的 acts。呼叫前請確認以下事項：

驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
前置條件：Travel 的 creationModel 必須為 scriptlist，狀態需為 running 或 pending。可透過查詢Travel狀態介面确认。
呼叫方：您的伺服器端或用戶端均可呼叫。

HTTP 呼叫

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/update-script

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

美国（維吉尼亞）

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

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

請求參數

劇本全量更新

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/update-script' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "scriptList": {
        "acts": [
            {
                "turn": 1,
                "content": "[character_1] wakes up and looks toward the door.",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] walks slowly across the dark room.",
                "cameraType": "Tracking",
                "shotSize": "Wide",
                "cut": "hard-cut"
            }
        ]
    },
    "userAgent": "your-client/1.2.0"
}'

範例中僅展示第 1、2 個 act 用於說明結構，不可直接提交。實際請求必須包含 turn 1–45 共 45 條，連續且不重複。

Content-Typestring（必選）

請求內容類型。此參數必須設定為 application/json。

Authorization string （必選）

API Key 驗證。不強制使用主 API Key，主 API Key 或臨時 API Key 均可呼叫。

主 API Key：以 sk- 開頭，如 sk-xxx。
臨時 API Key：以 st- 開頭，如 st-xxx。

請求主體（Request Body）

encryptedTravelId string （必選）

要更新的 Directing 加密 Travel ID，creationModel 必須為 scriptlist。由客戶端進入房間介面返回。

scriptList object （必選）

全量劇本容器。僅 acts 生效；即使包含 subjects、synopsis、scene、style、speed、language、setting、soundtrack、prologue 或 videoTags，這些欄位也會被忽略，平台继续使用建立 World 時已儲存的值。

scriptList.acts array （必選）

完整 act 列表。約束：

必須恰好 45 條
turn 必須覆蓋 1–45，連續且不可重複
content 非空，單拍最長 2000 字；全部 content 合計最長 100000 字
cameraType（可選，預設 Static）、shotSize（可選 Wide / Medium / Close-up，預設 Medium）、cut（可選，預設 long-take）

本接口是全量替換，不支持只提交發生變化的 turn。

userAgent string （可選）

SDK 或用戶端版本識別碼。非空字串，優先於 HTTP User-Agent。

回應參數

更新已接受

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "accepted": true,
        "turnCount": 45
    }
}

code integer

返回碼。0 表示成功，非 0 為錯誤碼。

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

加密的 Travel ID。

accepted boolean

是否已接受完整劇本並進入處理流程。

turnCount integer

本次全量更新的 turn 數，固定為 45。

前置狀態與呼叫注意事項

僅 creationModel=scriptlist 支持本接口；普通模式 Travel 誤調用返回 409000。
Travel 狀態必須為 running 或 pending。
acts 必須恰好 45 條；turn 必須為 1–45，連續且不可重複，否則返回 400000。
劇本內容未通過內容安全策略時返回 403004；觸發版權或 IP 合規拒絕時返回 403005。

錯誤碼

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

下一步

更新後：

查詢Travel狀態：檢視章節資訊。
暫停Travel / 回溯Travel。
結束Travel：結束工作階段並處理產物。