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

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

Scope

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-directing/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-directing/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-directing/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 Directing 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 equal 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-06-04T00:02:00Z",
        "userInstructions": [
            {
                "instruction": "A giant robotic dinosaur suddenly appears",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "Chapter 1",
                "brief": "The detective enters the cyberpunk city",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}

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 call the supported control endpoints according to the creation submode
paused: server-side pause completed; can be resumed or rewound
failed: the Travel failed
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, relativeStartTimeMs / relativeEndTimeMs (relative milliseconds), startTime / endTime (timeline seconds), and status.

chapters array

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

characterActions array

Fixed as an empty array for the Directing model.

environmentActions array

Fixed as an empty array for the Directing model.

Prerequisite states and call notes

Poll every 2–5 seconds.
In the running status, you can call the supported control endpoints according to creationModel: standard mode supports instruct, pause, resume, rewind, and end; script mode supports update-script, pause, resume, rewind, and end.
This endpoint does not return mode, aspectRatio, playUrl, bgmUrl, or sessionId; the streaming configuration is 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.

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:

Standard mode: Send Process Instruction.
Script mode: Full script update.
Common: Pause / Resume / Rewind / End.