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

Send a single text instruction to an Acting Travel to drive subsequent role-play and frame generation. Callable when the Travel is running or paused.

Scope

Send a single text instruction to an Acting Travel to drive subsequent role-play and 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 state must be running or paused. 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-acting/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-acting/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-acting/openapi/v1/travels/instruct' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "content": "Smile and greet me, and ask how my day is going",
    "clientRequestId": "instruction_greeting_001",
    "userAgent": "HappyOyster-Web/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 Acting encrypted Travel ID to control. Returned by Enter Travel.

content string (Required)

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

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": "Smile and greet me, and ask how my day is going",
        "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

The Travel's state must be running or paused.
content is required and cannot be empty or contain only whitespace characters, up to 2000 characters.
Sending an instruction in the paused state only accepts the instruction and does not automatically resume the Travel; when you need to continue running, the client must separately call Resume Travel.
Reuse the clientRequestId when retrying the same logical instruction to avoid duplicate billing.
A Travel that has ended or failed is not writable.
When the instruction fails the content safety policy, 403004 is returned.
Acting's creationModel is always simple, so there is no need to consider the ScriptList sub-mode.

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: control the running pace.
End Travel: end the session and process artifacts.