Skip to main content
Acting Open API Reference (Invitational Preview)

HappyOyster-Acting-Enter Travel API Reference

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
  • US (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/enter-travelReplace {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.
Acting 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 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 stringThe newly created encrypted Travel ID. Used for subsequent Query Travel Status, pause, resume, end, and artifacts queries.encryptedWorldId stringThe encrypted World ID that this Travel corresponds to.mode integerAlways 3 for Acting.creationModel stringAlways simple for Acting.playUrl nullNot available yet; fixed to null.firstFrame stringWorld first-frame URL.rtcConfig objectRTC 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 stringThe Acting enter-room version, fixed to actingV2. Control interfaces must be called according to this version.aspectRatio stringAspect ratio. The client must set the player orientation accordingly before pulling the stream:
  • 9:16 (portrait)
  • 16:9 (landscape)
noStreamAutoEndTimeoutSec integerNo-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 nullActing 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:
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