DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) World models HappyOyster Acting Open API Reference (Invitational Preview) Acting-Enter Travel

HappyOyster-Acting-Enter Travel API Reference

Updated at:
Copy as MD
Product
My Favorites

The client uses the ticket to create an actual Travel and obtain the RTC join configuration, the Acting capability version, and the player aspect ratio. A successful call creates the Travel.

Scope

The client uses the ticket to create an actual Travel and obtain the RTC join configuration, the Acting capability version, and the player aspect ratio. 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-acting/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-acting/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-acting/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}"
}'

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.

NoteActing does not consume maxExperienceTimeSec; do not pass it. If an invalid tier is still passed, 400000 is returned before model routing.

Response parameters

Entered successfully

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 3,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/acting_world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "actingV2",
        "aspectRatio": "9:16",
        "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, pause, resume, end, and artifacts queries.

encryptedWorldId string

The encrypted World ID that this Travel corresponds to.

mode integer

Always 3 for Acting.

creationModel string

Always simple for Acting.

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 Acting enter-room version, fixed to actingV2. Control interfaces must be called according to this version.

aspectRatio string

Aspect ratio. The client must set the player orientation accordingly before pulling the stream:

  • 9:16 (portrait)
  • 16:9 (landscape)

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

Acting does not use the maximum experience duration; fixed to null.

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.
  • When the Acting feature or specification is not enabled, 403007 is returned, and no Travel is created.
  • version must be handled as actingV2; do not call control interfaces according to another capability version.
  • The client should read aspectRatio before establishing the stream pull or the rendering container: use a portrait container for 9:16 and a landscape container for 16:9.
  • Do not pass maxExperienceTimeSec. Acting does not auto-end by this field, and the client must not use it to implement a countdown.
  • 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:

Previous：Acting-Get Travel CredentialNext：Acting-Query Travel Status