Skip to main content
Adventure Open API Reference

HappyOyster-Adventure-Query Travel Status API Reference

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
  • China (Beijing)
  • US (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/statusReplace {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 integerReturn code. 0 means success; non-zero is an error code.
message stringError message. null on success.
data objectResponse data. null on failure.

Properties

encryptedTravelId stringEncrypted Travel ID.status stringTravel 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 stringServer-side RTC streaming status; different from the clientStreamStatus reported by the client.updateTime stringLast update time, in ISO 8601 format.userInstructions null | arrayAdventure does not support HTTP instruct, and exploration actions are not echoed to this field; usually null or [], and can be ignored.chapters arrayThe chapter list; null when no chapter data has been generated.characterActions arrayAvailable 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 arrayAvailable 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.
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More