HappyOyster-Directing-Send Process Instruction API Reference - Alibaba Cloud Model Studio

Send a single text instruction to a standard-mode Travel to drive subsequent frame generation. Only creationModel=simple is supported; a scriptlist Travel should use full script update.

Scope

Send a single text instruction to a standard-mode (creationModel=simple) Travel to drive subsequent frame generation. 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 simple, and it must be in a state that can receive instructions. 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/instruct

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/instruct

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters

Send process instruction

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/instruct' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "content": "A giant robot dinosaur suddenly appears",
    "clientRequestId": "instruction_20260909_001",
    "userAgent": "your-client/1.2.0"
}'

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 control; creationModel must be simple. Returned by Enter Travel.

content string (Required)

The text process instruction. Non-empty, up to 2000 characters; returns 400000 when empty or over 2000 characters.

clientRequestId string (Optional)

Idempotency key for instruction retries. Reuse the same value when retrying the same instruction to avoid duplicate billing. Recommended format [A-Za-z0-9_-]{1,32}.

Being omitted or malformed does not return a parameter error: the server falls back to the gateway request_id, and uses a random idempotency key when that is still unavailable
This field is only used for billing deduplication; it does not guarantee that the instruction processing itself runs exactly once

userAgent string (Optional)

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

Response parameters

Instruction accepted

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "content": "A giant robot dinosaur suddenly appears",
        "accepted": true
    }
}

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.

content string

The accepted instruction text.

accepted boolean

Whether the instruction has been accepted and entered the processing flow.

Prerequisite states and call notes

Only creationModel=simple supports this endpoint; a scriptlist Travel should use Full Script Update, and calling instruct by mistake returns 403006.
The Travel's current state must be able to receive instructions; a Travel that has ended or failed is not writable.
When content is empty or over 2000 characters, 400000 is returned.
We recommend generating a stable clientRequestId for each logical instruction and reusing it on retries.
When the instruction fails the content safety policy, 403004 is returned.

Error codes

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

Next steps

After sending the instruction:

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