HappyOyster-Acting-傳送文字過程指令 API 參考 - Alibaba Cloud Model Studio

向 Acting Travel 傳送一條文字指令，驅動後續角色表演和畫面生成。Travel 為 running 或 paused 時可呼叫。

適用範圍

向 Acting Travel 傳送一條文字指令，驅動後續角色表演和畫面生成。呼叫前請確認以下事項：

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

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

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

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

請求參數

傳送文字過程指令

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/instruct' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "content": "微笑着问候，并询问我今天过得怎么样",
    "clientRequestId": "instruction_greeting_001",
    "userAgent": "HappyOyster-Web/1.2.0"
}'

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 （必選）

要控制的 Acting 加密 Travel ID。由用戶端進入房間介面返回。

content string （必選）

文字過程指令。非空，最長 2000 字元；缺失、為空或超限返回 400000。

clientRequestId string （可選）

指令重試的計費冪等鍵。同一條邏輯指令重試時複用同值，避免重複計費。推薦格式 [A-Za-z0-9_-]{1,32}。

缺省或格式不符合建議時不會返回參數錯誤：伺服器端會回退使用網關 request_id，仍不可用時使用隨機計費冪等鍵
該欄位僅用於計費去重，不保證指令處理本身只執行一次

userAgent string （可選）

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

回應參數

指令已接受

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "content": "微笑着问候，并询问我今天过得怎么样",
        "accepted": true
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

加密的 Travel ID。

content string

已接受的指令文字。

accepted boolean

是否已接受指令並進入處理流程。

前置狀態與呼叫注意事項

Travel 狀態必須為 running 或 paused。
content 為必填、不可為空或僅含空白字元，最長 2000 字元。
在 paused 狀態傳送指令只會接受指令，不會自動恢復 Travel；需要繼續運行時，用戶端必須另行呼叫恢復Travel。
同一條邏輯指令重試時應複用 clientRequestId，以避免重複計費。
已結束或失敗的 Travel 不可寫入。
指令未通過內容安全策略時返回 403004。
Acting 的 creationModel 恆為 simple，不需要判斷 ScriptList 子模式。

錯誤碼

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

下一步

傳送指令後：

查詢Travel狀態：檢視指令執行狀態和章節資訊。
暫停Travel / 恢復Travel：控制運行節奏。
結束Travel：結束工作階段並處理產物。