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

Query the Adventure Travel lifecycle, server-side streaming status, and the current world's action pool; you can also report the client's pull-stream or playback heartbeat at the same time.

Scope

Query the Adventure Travel lifecycle, server-side streaming status, and the current world's action pool; 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-adventure/openapi/v1/travels/status

Replace {WorkspaceId} with your actual Workspace ID.

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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-adventure/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-adventure/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 Adventure 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 Adventure Travel supports 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": null,
        "chapters": null,
        "characterActions": [
            "dash",
            "jump",
            "crouch",
            "attack"
        ],
        "environmentActions": [
            "ride_motorcycle",
            "enter_exit_car"
        ]
    }
}

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 control it in real time via the SDK sendCommand
failed: the Travel failed
completed: the Travel has ended; artifacts can be queried

Adventure product capabilities have no paused state; do not build a state machine around pause / resume.

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 null | array

Adventure does not support HTTP instruct, and exploration actions are not echoed to this field; usually null or [], and can be ignored.

chapters array

The chapter list; null when no chapter data has been generated.

characterActions array

Available action IDs for the current character / subject; [] when there is no recommendation. Usually 2–4 are returned. Common actions:

dash: dash forward
jump: jump
crouch: crouch / go prone
attack: attack

environmentActions array

Available environment-interaction action IDs for the current scene; [] when there is no recommendation. The server selects 0–3 from a fixed action pool by scene and may return an empty array. Common actions:

ride_horse: ride a horse
ride_bicycle: ride a bicycle
ride_motorcycle: ride a motorcycle
enter_exit_car: enter / exit a car
open_close_door: open / close a door
take_cover: take cover
car_light: turn on car lights; may appear only when enter_exit_car is also returned
car_horn: honk the horn; may appear only when enter_exit_car is also returned

Prerequisite states and call notes

Poll every 2–5 seconds.
Adventure product capabilities have no paused state; do not build a state machine around pause / resume.
characterActions and environmentActions are available-action hints; actual control is still sent via the SDK sendCommand.
This endpoint does not return mode, 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.
Adventure does not support HTTP instruct, pause, resume, rewind, or update-script; do not integrate the following paths as available HTTP capabilities: /travels/instruct, /travels/pause, /travels/resume, /travels/rewind, /travels/update-script.

Error codes

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

Next steps

After the Travel becomes running:

The client sends direction, viewpoint, and action controls via the SDK sendCommand (you can first read the action pool returned by this endpoint).
End Travel: end the session and handle the artifacts.