Skip to main content
Directing Open API Reference

HappyOyster-Directing-Query Travel Status API Reference

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

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. 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
  • US (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/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-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 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 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 stringServer-side RTC streaming status; different from the clientStreamStatus reported by the client.updateTime stringLast update time, in ISO 8601 format.userInstructions arrayThe 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 arrayThe chapter list; null when chapter detection has not been triggered yet. Each item contains chapterId, title, brief, actRange, startTime, endTime, and chapterImage.characterActions arrayFixed as an empty array for the Directing model.environmentActions arrayFixed 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:
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