HappyOyster-Adventure-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 Adventure capability version. maxExperienceTimeSec takes effect only in the Adventure model.

Scope

The client uses the ticket to create an actual Travel and obtain the RTC join configuration. maxExperienceTimeSec takes effect only in the Adventure model. 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-adventure/openapi/v1/travels/enter-travel

Replace {WorkspaceId} with your actual Workspace ID.

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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-adventure/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-adventure/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}",
    "maxExperienceTimeSec": 90
}'

Content-Typestring(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.

maxExperienceTimeSec integer (Optional)

Maximum experience duration, in seconds, must be a JSON integer. Defaults to 60. Allowed values:

60
90
120

Strings and other numeric values are not accepted (e.g. "60" is not valid); an invalid tier returns 400000. The server automatically ends the Travel once this duration is reached.

Response parameters

Entered successfully

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 1,
        "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": "wanderV2",
        "aspectRatio": null,
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": 90
    }
}

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, end, and artifacts queries.

encryptedWorldId string

The encrypted World ID that this Travel corresponds to.

mode integer

Always 1 for Adventure.

creationModel string

Always simple for Adventure.

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 Adventure enter-room version, fixed to wanderV2. Control data must be sent via the SDK sendCommand according to this version.

aspectRatio null

Fixed to null for Adventure; the player aspect ratio is not read from this field and follows the first-frame image ratio.

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 integer

The experience duration actually adopted by the server; it can only be 60 / 90 / 120. The server automatically ends the Travel once this duration is reached.

Prerequisite states and call notes

The World corresponding to the ticket must be ready, and the ticket must be unexpired and unused.
A successful call creates the Travel; reusing the same ticket returns 401011.
version must be handled as wanderV2; do not send control data using another model's interaction protocol.
The server ends the experience once maxExperienceTimeSec is reached; the client should handle the terminal state that arrives afterward.
Adventure's direction, viewpoint, and action controls are not server-side HTTP Open APIs; the client must use the corresponding platform SDK's sendCommand, which the SDK sends over the RTC DataChannel.
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 to read the available action pool.
After the Travel becomes running, the client sends direction, viewpoint, and action controls via the SDK sendCommand.
End Travel: end the session and handle the artifacts.