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
ticketcompletes the enter-room validation. For how to obtain it, see Obtain authentication credentials. - Prerequisites: The
ticketis obtained from Get Travel Credential, unexpired and unused, and its World status isready. - 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-directing/openapi/v1/travels/enter-travelReplace {WorkspaceId} with your actual Workspace ID.Request parameters |
|
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.
| |
Request Body | |
ticket string (Required)An unexpired, unused single-use credential obtained from Get Travel Credential. Reusing the same ticket returns 401011.Directing 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 | Entered successfully |
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, rewind, pause, resume, end, and artifacts queries.encryptedWorldId stringThe encrypted World ID that this Travel corresponds to.mode integerAlways 2 for Directing.creationModel stringsimple or scriptlist; determines the control interfaces the Travel can call:
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.
stringThe Directing enter-room version, fixed to storyV2.aspectRatio nullFixed to null for the Directing model.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 nullFixed to null for the Directing model. |
Prerequisite states and call notes
- The World corresponding to the
ticketmust beready, 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
ticketreturns401011. - When
creationModel=scriptlist, do not callinstruct; use Full script update instead. rtcConfig=nullmeans 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.