HappyOyster-Acting-Query Travel Status API Reference - Alibaba Cloud Model Studio

Query the Acting Travel lifecycle, server-side streaming status, sent text instructions, and chapter information; you can also report the client's pull-stream or playback heartbeat at the same time.

Scope

Query the Acting Travel lifecycle, server-side streaming status, sent text instructions, and chapter information; you can also report the client's pull-stream or playback heartbeat at the same time. 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: Query with the encryptedTravelId returned by Enter Travel.
Caller: Either your server or your client can call it. Polling every 2–5 seconds is recommended.

HTTP request

Singapore

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

Replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

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

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters

Query Travel status

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/status?encryptedTravelId={encryptedTravelId}&clientStreamStatus=PLAYING&clientStreamStatusTimeMs=1788940800000' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"

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.

Query parameters

encryptedTravelId string (Required)

The Acting encrypted Travel ID. Returned by Enter Travel.

clientStreamStatus string (Optional)

The client's RTC pull-stream or playback status, case-insensitive. Unrecognized values are ignored. Allowed values:

DISCONNECTED: not connected or has left the channel
CONNECTING: connecting to the RTC channel
CONNECTED: joined, but playback has not started or the first frame has not arrived
PLAYING: the remote stream has been received and is rendering
BUFFERING: buffering
PAUSED: the client paused playback; this does not mean the server-side pause
RECONNECTING: reconnecting

clientStreamStatusTimeMs long (Optional)

The millisecond timestamp of the client state change. Used together with clientStreamStatus.

Response parameters

Travel running

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-09-09T08:30:00Z",
        "userInstructions": [
            {
                "instruction": "Greet with a smile and ask how my day is going",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "Greeting",
                "brief": "The character smiles at the camera and starts the conversation",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/acting_ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}

Travel failed

See Error codes for errorCode values.

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "failed",
        "rtcStatus": null,
        "updateTime": null,
        "userInstructions": null,
        "chapters": null,
        "characterActions": null,
        "environmentActions": null,
        "errorCode": "TRAVEL_SESSION_INIT_FAILED",
        "errorMessage": "Failed to allocate inference resources."
    }
}

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

Encrypted Travel ID.

status string

Travel lifecycle status:

init: initializing session resources
pending: queued or waiting for service resources
running: running; you can send text instructions, pause, or end
paused: paused on the server side; you can send text instructions, resume, or end
failed: the Travel failed; see errorCode / errorMessage for the reason
completed: the Travel has ended; artifacts can be queried

rtcStatus string

Server-side RTC streaming status; different from the clientStreamStatus reported by the client.

updateTime string

Last update time, in ISO 8601 format.

userInstructions array

The list of text instructions; null when there is no data. Each item contains instruction (instruction text), relativeStartTimeMs / relativeEndTimeMs (relative milliseconds), startTime / endTime (timeline seconds), and status (execution status).

chapters array

The chapter list; null when chapter detection has not been triggered. Each item contains chapterId, title, brief, actRange, startTime, endTime, and chapterImage.

characterActions array<string> | null

Acting does not support SDK action control; returns an empty array; null when failed.

environmentActions array<string> | null

Acting does not support SDK environment action control; returns an empty array; null when failed.

errorCode string

Returned only when status=failed; a structured failure reason code. See Error codes for values.

errorMessage string

Returned together with errorCode; an English failure description. Branch on errorCode, not on errorMessage.

Prerequisite states and call notes

Polling every 2–5 seconds is recommended.
Both running and paused allow calling Send Process Instruction; sending an instruction in the paused state does not automatically resume the Travel.
This endpoint does not return mode, aspectRatio, playUrl, bgmUrl, or sessionId; the streaming configuration and player orientation are based on the Enter Travel response.
clientStreamStatus is the client-side playback heartbeat, and rtcStatus is the server-side streaming status; they are not interchangeable.
Acting does not support the SDK sendCommand; do not build direction or action controls based on the two empty action arrays.
failed is a terminal state and no video will be produced; show the failure reason based on errorCode, and do not display it as "not yet complete".

Error codes

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

Next steps

When the Travel is running or paused:

Send Process Instruction: drive the subsequent character performance.
Pause Travel / Resume Travel.
End Travel: query artifacts after ending.