HappyOyster-Directing-Enter Travel API Reference - Alibaba Cloud Model Studio

The client uses the ticket to create an actual Travel and obtain the RTC join configuration and the Directing capability version. creationModel determines the control interfaces the Travel can call.

Scope

The client uses the ticket to create an actual Travel and obtain the RTC join configuration. Before calling, confirm the following:

Authentication: The primary API Key is not required; the ticket completes the enter-room validation. For how to obtain it, see Obtain authentication credentials.
Prerequisites: The ticket is obtained from Get Travel Credential, unexpired and unused, and its World status is ready.
Caller: Called by your client.

HTTP request

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/enter-travel

Replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/enter-travel

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters	Enter travel (client) `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/enter-travel' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "ticket": "{ticket}" }'`
Content-Type`string`(Required) Request content type. This parameter must be set to `application/json`.
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`.
Request Body
ticket `string` (Required) An unexpired, unused single-use credential obtained from Get Travel Credential. Reusing the same `ticket` returns `401011`. NoteDirecting enter-travel does not consume `maxExperienceTimeSec`; do not pass it. This field only takes effect for Adventure; if an invalid tier is passed, `400000` is returned before model routing. The successful response is still `null`.

Response parameters

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 2,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "storyV2",
        "aspectRatio": null,
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": null
    }
}

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

The newly created encrypted Travel ID. Used for subsequent Query Travel Status, rewind, pause, resume, end, and artifacts queries.

encryptedWorldId string

The encrypted World ID that this Travel corresponds to.

mode integer

Always 2 for Directing.

creationModel string

simple or scriptlist; determines the control interfaces the Travel can call:

simple: instruct, pause, resume, rewind, end
scriptlist: update-script, pause, resume, rewind, end (instruct not supported)

playUrl null

Not available yet; fixed to null.

firstFrame string

World first-frame URL.

rtcConfig object

RTC join configuration; null when there is no available streaming channel, in which case the client cannot start playback based on it.

channelId: RTC channel ID
appId: RTC application ID assigned by the platform
token: RTC join token
userId: RTC join user ID, fixed to user_1

version string

The Directing enter-room version, fixed to storyV2.

aspectRatio null

Fixed to null for the Directing model.

noStreamAutoEndTimeoutSec integer

No-stream auto-end timeout in seconds, defaults to 30; the actual response prevails. If rtcStatus does not enter the streaming state within this time after entering the room, call End Travel with failCode=TRAVEL_NO_STREAM_AUTO_END.

maxExperienceTimeSec null

Fixed to null for the Directing model.

Prerequisite states and call notes

The World corresponding to the ticket must be ready, and the ticket must be unexpired and unused.
Do not pass maxExperienceTimeSec. Directing does not limit the experience time by this field.
A successful call creates the Travel; reusing the same ticket returns 401011.
When creationModel=scriptlist, do not call instruct; use Full script update instead.
rtcConfig=null means there is currently no available streaming channel, and the client cannot start playback based on it.

Error codes

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

Next steps

After entering the room successfully:

Query Travel Status: poll every 2–5 seconds, and call the available control interfaces according to creationModel.
Standard mode: Send Process Instruction.
Script mode: Full script update.
Common: Pause / Resume / Rewind / End.