HappyOyster-Directing-Update Script API Reference - Alibaba Cloud Model Studio

Submit the complete set of 45 turns in a script-mode Travel to fully replace the current Travel's acts. Only creationModel=scriptlist is supported.

Scope

Submit the complete set of 45 turns in a script-mode (creationModel=scriptlist) Travel to fully replace the current Travel's acts. Before calling, confirm the following:

Authentication: The primary API Key is not required; either the primary or a temporary API Key can call it. For how to obtain them, see Obtain authentication credentials.
Prerequisites: The Travel's creationModel must be scriptlist, and its status must be running or pending. Confirm via Query Travel Status.
Caller: Either your server or your client can call it.

HTTP request

Singapore

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

Replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

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

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters

Update script

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"
}'

The example shows only acts 1 and 2 to illustrate the structure and must not be submitted as-is. An actual request must contain all 45 entries, turn 1–45, contiguous and non-duplicated.

Content-Typestring(Required)

Request content type. This parameter must be set to application/json.

Authorization string (Required)

API Key authentication. The primary API Key is not required; either the primary or a temporary API Key can call it.

Primary API Key: starts with sk-, e.g. sk-xxx.
Temporary API Key: starts with st-, e.g. st-xxx.

Request Body

encryptedTravelId string (Required)

The Directing encrypted Travel ID to update; its creationModel must be scriptlist. Returned by Enter Travel.

scriptList object (Required)

Full script container. Only acts takes effect; even if it includes subjects, synopsis, scene, style, speed, language, setting, soundtrack, prologue, or videoTags, these fields are ignored and the platform continues to use the values saved at World creation.

scriptList.acts array (Required)

Complete act list. Constraints:

Must be exactly 45 entries
turn must cover 1–45, contiguous and non-duplicated
content non-empty, up to 2000 characters per beat; all content totaling up to 100000 characters
cameraType (optional, default Static), shotSize (optional, Wide / Medium / Close-up, default Medium), cut (optional, default long-take)

This endpoint is a full replacement and does not support submitting only the changed turns.

userAgent string (Optional)

SDK or client version identifier. A non-empty string; takes precedence over the HTTP User-Agent.

Response parameters

Update accepted

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

code integer

Return code. 0 means success; non-zero is an error code.

message string

Error message. null on success.

data object

Response data. null on failure.

Properties

encryptedTravelId string

The encrypted Travel ID.

accepted boolean

Whether the complete script has been accepted and entered the processing flow.

turnCount integer

The number of turns in this full update, fixed at 45.

Prerequisite states and call notes

Only creationModel=scriptlist supports this endpoint; a standard-mode Travel that calls it by mistake returns 409000.
The Travel status must be running or pending.
acts must be exactly 45 entries; turn must be 1–45, contiguous and non-duplicated, otherwise 400000 is returned.
Script content that fails the content-safety policy returns 403004; a copyright or IP compliance rejection returns 403005.

Error codes

If the model call fails and returns an error, see HappyOyster Error Codes to resolve it.

Next steps

After updating:

Query Travel Status: view chapter information.
Pause Travel / Rewind Travel.
End Travel: end the session and process artifacts.