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
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 statuscurl --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": []
}
}
Travel failederrorCode values are described in Error Codes.
{
"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 call the supported control endpoints according to the creation submode
paused: server-side pause completed; can be resumed or rewound
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, 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<string> | null Directing does not support SDK action control, so this is always an empty array; null when failed. environmentActions array<string> | null Directing does not support SDK environment action control, so this is always an empty array; null when failed. errorCode string Returned only when status=failed; the structured failure reason code. For values, see Error Codes. errorMessage string Returned together with errorCode; an English failure description. Branch on errorCode instead of matching the errorMessage text. |
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.
failed is a terminal state; no final video will be produced. Show the failure reason based on errorCode; do not display it as "not completed yet".
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: