BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
HappyOyster-Adventure-Get Referência da API de credenciais de viagem
Um servidor de terceiros usa a chave de API primária para trocar por um tíquete de uso único e de curta duração e, em seguida, entrega-o com segurança ao cliente. Este endpoint valida apenas propriedade, status e cota mundial; isso não cria uma viagem.
Escopo
Antes de ligar, confirme o seguinte:
- Somente a chave API primária é suportada; Chaves de API temporárias não podem ser usadas (código de erro
403003). - O Mundo deve pertencer à conta primária atual e ao modelo Aventura, e seu status deve ser
ready. - Chamado pelo seu servidor; o resultante
ticketdeverá ser entregue apenas a um cliente que esteja prestes a entrar imediatamente na sala.
Se a chamada do modelo falhar e retornar um erro, consulte HappyOyster Códigos de erro.
OpenAPI
openapi: 3.1.0
info:
title: HappyOyster Adventure Open API
description: HappyOyster world-exploration (Adventure) mode Open API. Create and manage Worlds, exchange travel credentials, and query history and artifacts. Server-side calls use the primary API Key over standard HTTPS REST. Clients experience the World in real time over the RTC channel using a temporary API Key and a ticket.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: QwenCloud
security:
- BearerAuth: []
paths:
/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/get-travel-credential:
post:
operationId: getAdventureTravelCredential
summary: Get Travel Credential
description: "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. Authentication: only the primary API Key is supported; temporary API Keys cannot be used (error code 403003). The World must belong to the current primary account and the Adventure model, and its status must be ready. Server-side call; the resulting ticket should be delivered only to a client that is about to enter the room immediately."
parameters:
- name: Content-Type
in: header
required: true
schema:
type: string
default: application/json
description: Request content type. This parameter must be set to application/json.
- name: Authorization
in: header
required: true
schema:
type: string
description: 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.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AdventureGetTravelCredentialRequest"
responses:
"200":
description: Credential exchanged successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/TravelCredentialResponse"
examples:
credential_success:
summary: Exchange succeeded
value:
code: 0
message: null
data:
ticket: tk_a1b2****
expiresIn: 1800
encryptedWorldId: enc_a1b2****
"400":
description: Request parameter error.
content:
application/json:
schema:
$ref: "#/components/schemas/HappyOysterErrorResponse"
"403":
description: Authentication or permission error (e.g. calling with a temporary API Key, or referencing resources across primary accounts).
content:
application/json:
schema:
$ref: "#/components/schemas/HappyOysterErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Get travel credential
source: |-
curl --location 'https://maas.qwencloudapi.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/get-travel-credential' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"encryptedWorldId": "{encryptedWorldId}"
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: QwenCloud API Key. Only the primary API Key (sk- prefix) is supported. See [Get an API Key](/api-reference/preparation/api-key).
schemas:
AdventureCreateWorldRequest:
type: object
required:
- perspective
- prompt
- firstFrameImage
description: Adventure Create World request body.
properties:
async:
type: boolean
description: "Whether to create asynchronously. Defaults to true. true: returns immediately; the World builds in the background, and the client polls Query World Build Status. false: the server polls every 3 seconds for up to 120 seconds and returns when the build completes; on timeout it still returns generating, and the client then polls on its own."
default: true
perspective:
type: string
description: Perspective. Omitting this field returns 400000.
enum:
- first_person
- third_person
prompt:
type: string
description: World theme description; Chinese and English are supported. Non-empty, up to 2000 characters. Missing, blank, or over-length returns 400000.
creationModel:
type: string
description: Creation sub-mode. Defaults to simple; Adventure supports only simple.
default: simple
enum:
- simple
uploadMode:
type: string
description: Image upload mode. Defaults to first_frame; Adventure supports only first_frame.
default: first_frame
enum:
- first_frame
eventStyle:
type: string
description: "Event style, used to select the script-generation template. Defaults to normal. normal: regular / standard style (default). Completes 4-5 acts per the user's intent at a relatively steady pace, without forcing conflict, reversals, or a three-act climax. dramatic: dramatic / conflict style. Generates a script on a roughly 180-second three-act skeleton: opening hook, rising conflict, turning point, climactic resolution; for open-ended performance it arranges reversals by genre (mystery / thriller / comeback, etc.), with a denser pace and stronger drama. regular: legacy value, equivalent to normal. Kept only for backward compatibility with historical inputs; the server parses it as normal with identical behavior. Do not use it in new calls."
default: normal
enum:
- normal
- dramatic
- regular
refWorldId:
type: string
description: Derive a new creation from an existing Adventure World. Must be an Adventure encrypted World ID under the current primary account; a World from another model or another primary account returns 403001.
firstFrameImage:
$ref: "#/components/schemas/FirstFrameImage"
FirstFrameImage:
type: object
description: "An image reference reused directly as the World's first frame. url and base64 are mutually exclusive (choose one). Image constraints: format JPG/JPEG/PNG/WebP; strictly less than 6 MB per image; aspect ratio must be landscape, width/height of 1.5-2.0; failing content-safety or copyright/IP verification returns 403004/403005."
properties:
url:
type: string
description: First-frame image URL. Mutually exclusive with base64 (choose one). Must be a valid http/https URL with a host, accessible by the server. The actual format, size, and first-frame aspect ratio are validated after storage. An async request may first return generating, then the World enters failed due to image validation failure.
base64:
type: string
description: First-frame image base64. Mutually exclusive with url (choose one). A complete data URI data:image/<subtype>;base64,<payload> is recommended. Format, size, and first-frame aspect ratio are validated synchronously at the creation entry point.
referenceType:
type: string
description: Reference-image type. Defaults to default, and is currently used as default.
default: default
CreateWorldResponse:
type: object
description: Create World response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedWorldId:
type: string
description: The encrypted World ID generated by the server. Returned in both synchronous and asynchronous modes; used for subsequent build-status polling, detail queries, and exchanging a travel credential.
status:
type: string
description: "Current creation status: generating (building) or ready; may also be failed when a synchronous build fails."
enum:
- generating
- ready
- failed
firstFrame:
type: string
description: World first-frame URL; null before it is generated.
HappyOysterErrorResponse:
type: object
description: HappyOyster API error response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Human-readable error message. null on success.
data:
description: Response data. null on failure.
AdventureDeleteWorldRequest:
type: object
required:
- encryptedWorldId
description: Adventure Delete World request body.
properties:
encryptedWorldId:
type: string
description: The Adventure encrypted World ID to delete. Returned by Create World.
DeleteWorldResponse:
type: object
description: Delete World response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedWorldId:
type: string
description: The encrypted World ID from the request.
deleted:
type: boolean
description: true means it was deleted; false means no World was deleted this time.
AdventureEndTravelRequest:
type: object
required:
- encryptedTravelId
description: Adventure End Travel request body.
properties:
encryptedTravelId:
type: string
description: The Adventure encrypted Travel ID to end. Returned by Enter Travel (Client).
failCode:
type: string
description: "The failure end reason for a no-stream timeout. When omitted, it is treated as a normal end. Currently only supported: TRAVEL_NO_STREAM_AUTO_END (for the scenario where no stream is received after entering the room for longer than noStreamAutoEndTimeoutSec; this end type does not generate replay artifacts). Passing an unsupported value returns 400000."
enum:
- TRAVEL_NO_STREAM_AUTO_END
userAgent:
type: string
description: SDK or client version identifier. A non-empty string; takes precedence over the HTTP User-Agent.
EndTravelResponse:
type: object
description: End Travel response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedTravelId:
type: string
description: The encrypted Travel ID that was ended.
status:
type: string
description: "End status: completed (normal end) or failed (failure end when a supported failCode is provided)."
enum:
- completed
- failed
errorCode:
type: string
description: Failure reason code; null on a normal end.
errorMessage:
type: string
description: Failure description; null on a normal end.
endedAt:
type: string
description: End time, in ISO 8601 format.
durationSec:
type: integer
description: Effective video duration in seconds; null on a no-stream failure end or when the duration cannot yet be parsed.
AdventureEnterTravelRequest:
type: object
required:
- ticket
description: Adventure Enter Travel (client) request body.
properties:
ticket:
type: string
description: An unexpired, unused single-use credential obtained from Get Travel Credential. Reusing the same ticket returns 401011.
maxExperienceTimeSec:
type: integer
description: '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.'
enum:
- 60
- 90
- 120
default: 60
EnterTravelResponse:
type: object
description: Enter Travel (client) response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedTravelId:
type: string
description: The newly created encrypted Travel ID. Used for subsequent Query Travel Status, end, and artifacts queries.
encryptedWorldId:
type: string
description: The encrypted World ID that this Travel corresponds to.
mode:
type: integer
description: Always 1 for Adventure.
creationModel:
type: string
description: Always simple for Adventure.
playUrl:
type: string
description: Not available yet; fixed to null.
firstFrame:
type: string
description: World first-frame URL.
rtcConfig:
type: object
description: RTC join configuration; null when there is no available streaming channel, in which case the client cannot start playback based on it.
properties:
channelId:
type: string
description: RTC channel ID.
appId:
type: string
description: RTC application ID assigned by the platform.
token:
type: string
description: RTC join token.
userId:
type: string
description: RTC join user ID, fixed to user_1.
version:
type: string
description: The Adventure enter-room version, fixed to wanderV2. Control data must be sent via the SDK sendCommand according to this version.
aspectRatio:
type: string
description: Fixed to null for Adventure; the player aspect ratio is not read from this field and follows the first-frame image ratio.
noStreamAutoEndTimeoutSec:
type: integer
description: 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:
type: integer
description: 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.
AdventureGetTravelCredentialRequest:
type: object
required:
- encryptedWorldId
description: Adventure Get Travel Credential request body.
properties:
encryptedWorldId:
type: string
description: An Adventure World ID under the current primary account with status ready. Returned by Create World.
TravelCredentialResponse:
type: object
description: Get Travel Credential response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
ticket:
type: string
description: A single-use Travel credential prefixed with tk_. Valid for 1800 seconds (30 minutes) and can be used successfully only once.
expiresIn:
type: integer
description: Validity in seconds, fixed at 1800 (30 minutes).
encryptedWorldId:
type: string
description: The encrypted World ID that the credential corresponds to.
TravelArtifactsResponse:
type: object
description: Query Travel Artifacts response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedTravelId:
type: string
description: Encrypted Travel ID.
composeStatus:
type: string
description: "The aggregated status of the three composited variants: ready (withWatermark, withInstruction, and withInstructionAndWatermark are all ready), partial (at least one composited variant is ready, but not all), processing (none of the three composited variants is ready). It aggregates only the three composited variants and does not include original."
enum:
- ready
- partial
- processing
video:
type: object
description: The four fixed variants of the main video. Each item contains url, status, resolution, and durationSec.
properties:
original:
$ref: "#/components/schemas/TravelArtifactVideoVariant"
withWatermark:
$ref: "#/components/schemas/TravelArtifactVideoVariant"
withInstruction:
$ref: "#/components/schemas/TravelArtifactVideoVariant"
withInstructionAndWatermark:
$ref: "#/components/schemas/TravelArtifactVideoVariant"
TravelArtifactVideoVariant:
type: object
description: Video variant info.
properties:
url:
type: string
description: Download URL; null when processing or unavailable.
status:
type: string
description: "Per-item status: ready (ready, url is accessible), processing (still compositing, url=null), unavailable (composition failed or the URL is temporarily unavailable, url=null)."
enum:
- ready
- processing
- unavailable
resolution:
type: string
description: '"720p" when original matches 720p; otherwise it may be null.'
durationSec:
type: integer
description: The uniformly parsed video duration in seconds; when parseable, all ready variants carry this value. It may be null when processing / unavailable or when the duration cannot yet be parsed.
TravelListResponse:
type: object
description: Query Travel List response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
items:
type: array
description: The Travels on the current page; an empty array when there is no result. Each item contains encryptedTravelId, status, mode (always 1), encryptedWorldId, durationSec (null when running, failed, or the duration is not yet available), createdAt, and endedAt (null when still running).
items:
$ref: "#/components/schemas/TravelListItem"
pagination:
$ref: "#/components/schemas/Pagination"
TravelListItem:
type: object
description: Travel list item.
properties:
encryptedTravelId:
type: string
description: Encrypted Travel ID.
status:
type: string
description: "Travel lifecycle status: init, pending, running, failed, completed."
enum:
- init
- pending
- running
- failed
- completed
mode:
type: integer
description: Always 1 for Adventure.
encryptedWorldId:
type: string
description: The associated encrypted World ID.
durationSec:
type: integer
description: Effective video duration in seconds; null when running, failed, or the duration is not yet available.
createdAt:
type: string
description: Creation time, in ISO 8601 format.
endedAt:
type: string
description: End time, in ISO 8601 format; null when still running.
Pagination:
type: object
description: Pagination info.
properties:
page:
type: integer
description: Current page number.
pageSize:
type: integer
description: Items per page.
total:
type: integer
description: Total item count.
hasMore:
type: boolean
description: true when page * pageSize < total.
TravelStatusResponse:
type: object
description: Query Travel Status response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedTravelId:
type: string
description: Encrypted Travel ID.
status:
type: string
description: "Travel lifecycle status: init (initializing session resources), pending (queued or waiting for service resources), running (running; you can control it in real time via the SDK sendCommand), failed (the Travel failed), completed (the Travel has ended; artifacts can be queried). Adventure product capabilities have no paused state."
enum:
- init
- pending
- running
- failed
- completed
rtcStatus:
type: string
description: Server-side RTC streaming status; different from the clientStreamStatus reported by the client.
updateTime:
type: string
description: Last update time, in ISO 8601 format.
userInstructions:
type: array
description: The list of user text instructions; Adventure does not support HTTP instruct, so this is usually null.
items:
type: string
chapters:
type: array
description: The chapter list; null when no chapter data has been generated.
items:
type: object
characterActions:
type: array
description: "Available action IDs for the current character / subject; [] when there is no recommendation. Usually 2-4 are returned. Common actions: dash (dash forward), jump (jump), crouch (crouch / go prone), attack (attack)."
items:
type: string
environmentActions:
type: array
description: "Available environment-interaction action IDs for the current scene; [] when there is no recommendation. The server selects 0-3 from a fixed action pool by scene and may return an empty array. Common actions: ride_horse, ride_bicycle, ride_motorcycle, enter_exit_car, open_close_door, take_cover, car_light, car_horn."
items:
type: string
WorldBuildStatusResponse:
type: object
description: Query World Build Status response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedWorldId:
type: string
description: Encrypted World ID.
status:
type: string
description: "Build status: generating (building), ready (ready; you can exchange for a travel credential and enter the room), failed (build failed)."
enum:
- generating
- ready
- failed
firstFrame:
type: string
description: World first-frame URL; null when not yet generated or when the build failed.
name:
type: string
description: World name. Returned only when status=ready.
mode:
type: integer
description: Always 1 for Adventure. Returned only when status=ready.
WorldDetailResponse:
type: object
description: Query World Detail response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
encryptedWorldId:
type: string
description: Encrypted World ID.
name:
type: string
description: World name.
status:
type: string
description: "Build status: generating / ready / failed."
enum:
- generating
- ready
- failed
mode:
type: integer
description: Always 1 for Adventure.
creationModel:
type: string
description: Always simple for Adventure.
prompt:
type: string
description: The top-level prompt submitted at creation.
eventStyle:
type: string
description: "The event style at creation: normal / dramatic / regular."
enum:
- normal
- dramatic
- regular
perspective:
type: string
description: "Perspective: first_person / third_person."
enum:
- first_person
- third_person
uploadMode:
type: string
description: Fixed to first_frame.
resolution:
type: string
description: Adventure does not use this field; usually null.
aspectRatio:
type: string
description: Adventure does not use this field; fixed to null.
layout:
type: string
description: Adventure does not use this field; usually null.
narrative:
type: string
description: Adventure does not use this field; usually null.
refWorldId:
type: string
description: The encrypted reference World ID used for a derived creation; null if none.
firstFrameImage:
type: object
description: The required first-frame image at creation; returned in URL form only. Contains url and referenceType.
properties:
url:
type: string
description: First-frame image URL.
referenceType:
type: string
description: Reference-image type.
inputImages:
type: string
description: Adventure does not currently use this field.
sceneImage:
type: string
description: Adventure does not use this field; usually null.
roleImage:
type: string
description: Adventure does not use this field; usually null.
scenePrompt:
type: string
description: Adventure does not use this field; usually null.
rolePrompt:
type: string
description: Adventure does not use this field; usually null.
scriptList:
type: string
description: Adventure does not support ScriptList; fixed to null.
previewUrl:
type: string
description: Currently fixed to null.
createdAt:
type: string
description: Creation time, in ISO 8601 format.
updatedAt:
type: string
description: Last update time, in ISO 8601 format.
WorldListResponse:
type: object
description: Query World List response.
properties:
code:
type: integer
description: Return code. 0 means success; non-zero is an error code.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data. null on failure.
properties:
items:
type: array
description: The Worlds on the current page; an empty array when there is no result. Each item contains encryptedWorldId, name, status, mode (always 1), previewUrl (usually null), createdAt, perspective, creationModel (always simple), and uploadMode (fixed to first_frame).
items:
$ref: "#/components/schemas/WorldListItem"
pagination:
$ref: "#/components/schemas/Pagination"
WorldListItem:
type: object
description: World list item.
properties:
encryptedWorldId:
type: string
description: Encrypted World ID.
name:
type: string
description: World name.
status:
type: string
description: "Build status: generating / ready / failed."
enum:
- generating
- ready
- failed
mode:
type: integer
description: Always 1 for Adventure.
previewUrl:
type: string
description: Preview URL, usually null.
createdAt:
type: string
description: Creation time, in ISO 8601 format.
perspective:
type: string
description: "Perspective: first_person / third_person."
enum:
- first_person
- third_person
creationModel:
type: string
description: Always simple for Adventure.
uploadMode:
type: string
description: Fixed to first_frame.