HappyOyster-Directing-Get Travel Credential API Reference - Alibaba Cloud Model Studio

A third-party server uses the primary API Key to exchange for a short-lived, single-use ticket, then securely delivers it to the client. This endpoint only validates World ownership, status, and quota; it does not create a Travel.

Scope

A third-party server uses the primary API Key to exchange for a short-lived, single-use ticket, then securely delivers it to the client. Before calling, confirm the following:

Authentication: Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
- Get the primary API Key: Get and configure an API Key.
Prerequisites: The World must belong to the current primary account and the Directing model, and its status must be ready. Confirm via Query World Build Status.
Caller: Called by your server; the resulting ticket should be delivered only to a client that is about to enter the room immediately.

HTTP request

Singapore

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

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/worlds/get-travel-credential

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters	Get travel credential `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/get-travel-credential' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "encryptedWorldId": "{encryptedWorldId}" }'`
Content-Type`string`(Required) Request content type. This parameter must be set to `application/json`.
Authorization `string` (Required) API Key authentication. Only the primary API Key is supported; it starts with `sk-`, e.g. `sk-xxx`. It is typically configured as the environment variable `$DASHSCOPE_API_KEY`. A temporary API Key (starting with `st-`) returns `403003`.
Request Body
encryptedWorldId `string` (Required) A Directing World ID under the current primary account with status `ready`. Returned by Create World.

Response parameters

Exchange succeeded

{
    "code": 0,
    "message": null,
    "data": {
        "ticket": "tk_a1b2****",
        "expiresIn": 1800,
        "encryptedWorldId": "enc_a1b2****"
    }
}

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

ticket string

A single-use Travel credential prefixed with tk_. Valid for 1800 seconds (30 minutes) and can be used successfully only once.

expiresIn integer

Validity in seconds, fixed at 1800 (30 minutes).

encryptedWorldId string

The encrypted World ID that the credential corresponds to.

Prerequisite states and call notes

The World must be ready.
The ticket is valid for 30 minutes and can be used successfully only once; obtain a new one after it expires or has been used.
The ticket should be delivered only to a client that is about to enter the room immediately, and should not be persisted as a long-term access credential.
Calling this endpoint does not create a Travel; the Travel is created when entering the room succeeds.
If the quota for this World has not been purchased, 403007 is returned; if the capacity configuration is temporarily unavailable, 403008 is returned.

Error codes

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

Next steps

After obtaining the ticket:

Enter Travel: the client uses the ticket to create a Travel and obtain the RTC configuration.