BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
HappyOyster-Acting-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:
- Autenticação: somente a Chave de API primária é suportada; Chaves de API temporárias não podem ser usadas (código de erro
403003). - Pré-requisitos: O Mundo deve pertencer à conta primária atual e ao modelo de atuação, e seu status deve ser
ready. Confirme via Query World Build Status. - Chamador: 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 para resolvê-lo.
OpenAPI
openapi: 3.1.0
info:
title: HappyOyster Acting Open API
description: HappyOyster role-play (Acting) mode Open API. Create and manage Worlds, exchange travel credentials, enter a room on the client, send text process instructions, pause/resume/end Travels, and query history and artifacts. The server calls management endpoints with the primary API Key; the client experiences the real-time RTC channel via a temporary API Key and ticket. Defaults to 9:16 portrait streaming (16:9 landscape is also supported); rewind is not supported.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: QwenCloud
security:
- BearerAuth: []
paths:
/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds/get-travel-credential:
post:
operationId: getActingTravelCredential
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 Acting model, and its status must be ready. Called by the server; the resulting ticket should be delivered only to a client that is about to enter the room immediately."
x-codeSamples:
- lang: curl
label: cURL - Get travel credential
source: |-
curl --location 'https://maas.qwencloudapi.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds/get-travel-credential' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"encryptedWorldId": "{encryptedWorldId}"
}'
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/GetTravelCredentialRequest"
responses:
"200":
description: Exchange succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/GetTravelCredentialResponse"
examples:
success:
summary: Exchange succeeded
value:
code: 0
message: null
data:
ticket: tk_a1b2****
expiresIn: 1800
encryptedWorldId: enc_a1b2****
"400":
description: Invalid request parameters.
content:
application/json:
schema:
$ref: "#/components/schemas/HappyOysterErrorResponse"
"403":
description: Authentication or permission error (e.g. using a temporary API Key, or cross-account reference).
content:
application/json:
schema:
$ref: "#/components/schemas/HappyOysterErrorResponse"
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:
FirstFrameImage:
type: object
description: "An image reference reused 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; the width/height ratio must match aspectRatio (0.5-0.667 for 9:16, 1.5-2.0 for 16:9); 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: First-frame reference type. Defaults to default, and is currently used as default.
default: default
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.
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 (ready); may also be failed on a synchronous build failure."
enum:
- generating
- ready
- failed
firstFrame:
type: string
description: World first-frame URL; null before it is generated.
ActingCreateWorldRequest:
type: object
required:
- prompt
- firstFrameImage
description: Acting 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
creationModel:
type: string
description: Creation sub-mode. Defaults to simple; Acting supports only simple.
default: simple
enum:
- simple
prompt:
type: string
description: A natural-language description of the character, scene, and performance goal. Non-empty, up to 2000 characters. Missing, blank, or over-length returns 400000.
uploadMode:
type: string
description: Image upload mode. Defaults to first_frame; Acting supports only first_frame.
default: first_frame
enum:
- first_frame
resolution:
type: string
description: Video resolution. Defaults to 480p.
default: 480p
enum:
- 480p
- 720p
aspectRatio:
type: string
description: Streaming frame ratio, which also determines the first-frame image orientation; keeping the two consistent is recommended. Defaults to 9:16 (portrait); when landscape is needed, you must explicitly pass 16:9.
default: 9:16
enum:
- 9:16
- 16:9
refWorldId:
type: string
description: Derive a new creation from an existing Acting World. Must be an Acting encrypted World ID under the current primary account; a World from another model or another primary account returns 403001.
firstFrameImage:
$ref: "#/components/schemas/FirstFrameImage"
DeleteWorldRequest:
type: object
required:
- encryptedWorldId
description: Delete World request body.
properties:
encryptedWorldId:
type: string
description: The Acting 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.
GetTravelCredentialRequest:
type: object
required:
- encryptedWorldId
description: Get Travel Credential request body.
properties:
encryptedWorldId:
type: string
description: An Acting World ID under the current primary account with status ready. Returned by Create World.
GetTravelCredentialResponse:
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.
EndTravelRequest:
type: object
required:
- encryptedTravelId
description: End Travel request body.
properties:
encryptedTravelId:
type: string
description: The Acting 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 (no stream 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; returned only on a failure end.
errorMessage:
type: string
description: Failure description; returned only on a failure end.
endedAt:
type: string
description: End time, in ISO 8601 format; may be null when not yet available.
durationSec:
type: integer
description: Effective video duration in seconds; null on a no-stream failure end or when the duration cannot yet be parsed.
nullable: true
EnterTravelRequest:
type: object
required:
- ticket
description: 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. Acting does not use this value; the successful response is still null. If passed, it can only be one of the current configuration tiers (60/90/120). The parameter is validated before model routing; an invalid tier returns 400000. Omitting it is recommended.
enum:
- 60
- 90
- 120
RtcConfig:
type: object
description: RTC join configuration.
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.
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, pause, resume, end, and artifacts queries.
encryptedWorldId:
type: string
description: The encrypted World ID that this Travel corresponds to.
mode:
type: integer
description: Always 3 for Acting.
creationModel:
type: string
description: Always simple for Acting.
playUrl:
type: string
description: Not available yet; fixed to null.
nullable: true
firstFrame:
type: string
description: World first-frame URL.
rtcConfig:
$ref: "#/components/schemas/RtcConfig"
description: RTC join configuration; null when there is no available streaming channel, in which case the client cannot start playback based on it.
version:
type: string
description: The Acting enter-room version, fixed to actingV2. Control interfaces must be called according to this version.
aspectRatio:
type: string
description: "Aspect ratio. The client must set the player orientation accordingly before pulling the stream: 9:16 (portrait) or 16:9 (landscape)."
enum:
- 9:16
- 16:9
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: Acting does not use the maximum experience duration; fixed to null.
nullable: true
InstructTravelRequest:
type: object
required:
- encryptedTravelId
- content
description: Send Process Instruction request body.
properties:
encryptedTravelId:
type: string
description: The Acting encrypted Travel ID to control. Returned by Enter Travel (Client).
content:
type: string
description: The text process instruction. Non-empty, up to 2000 characters; returns 400000 when missing, empty, or over the limit.
clientRequestId:
type: string
description: "Idempotency key for instruction retries. Reuse the same value when retrying the same instruction to avoid duplicate billing. Recommended format [A-Za-z0-9_-]{1,32}. Being omitted or malformed does not return a parameter error: the server falls back to the gateway request_id, and uses a random idempotency key when that is still unavailable. This field is only used for billing deduplication; it does not guarantee that the instruction processing itself runs exactly once."
userAgent:
type: string
description: SDK or client version identifier. A non-empty string; takes precedence over the HTTP User-Agent.
InstructTravelResponse:
type: object
description: Send Process Instruction 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.
content:
type: string
description: The accepted instruction text.
accepted:
type: boolean
description: Whether the instruction has been accepted and entered the processing flow.
PauseResumeTravelRequest:
type: object
required:
- encryptedTravelId
description: Pause/Resume Travel request body.
properties:
encryptedTravelId:
type: string
description: The Acting encrypted Travel ID to control. Returned by Enter Travel (Client).
userAgent:
type: string
description: SDK or client version identifier. A non-empty string; takes precedence over the HTTP User-Agent, used for SDK version and platform statistics.
PauseResumeTravelResponse:
type: object
description: Pause/Resume 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.
status:
type: string
description: Returns paused on pause, and running on resume.
enum:
- paused
- running
VideoVariant:
type: object
description: A single video variant.
properties:
url:
type: string
description: Download URL; null when processing or unavailable.
nullable: true
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.'
nullable: true
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.
nullable: true
QueryTravelArtifactsResponse:
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: "Aggregated status of the three composited variants: ready (all ready), partial (at least one ready but not all), processing (none ready). Aggregates only the three composited variants; does not include original."
enum:
- ready
- partial
- processing
video:
type: object
description: The four fixed variants of the main video.
properties:
original:
$ref: "#/components/schemas/VideoVariant"
description: The recorded original; a 720p representation is returned preferentially when available.
withWatermark:
$ref: "#/components/schemas/VideoVariant"
description: Watermark-only composited variant.
withInstruction:
$ref: "#/components/schemas/VideoVariant"
description: Composited variant with the user's process-instruction overlay.
withInstructionAndWatermark:
$ref: "#/components/schemas/VideoVariant"
description: User's process-instruction overlay + watermark composited variant, recommended for external delivery.
Pagination:
type: object
description: Pagination info.
properties:
page:
type: integer
description: Current page number.
pageSize:
type: integer
description: Actual items per page.
total:
type: integer
description: Total number of records.
hasMore:
type: boolean
description: true when page * pageSize < total.
TravelListItem:
type: object
description: Travel list item.
properties:
encryptedTravelId:
type: string
description: Encrypted Travel ID.
status:
type: string
description: Travel status.
enum:
- init
- pending
- running
- paused
- failed
- completed
mode:
type: integer
description: Always 3 for Acting.
encryptedWorldId:
type: string
description: Associated encrypted World ID.
durationSec:
type: integer
description: Effective video duration in seconds; null when running, failed, or the duration is not yet available.
nullable: true
createdAt:
type: string
description: Creation time, in ISO 8601 format.
endedAt:
type: string
description: End time, in ISO 8601 format; null when still running.
nullable: true
QueryTravelListResponse:
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.
items:
$ref: "#/components/schemas/TravelListItem"
pagination:
$ref: "#/components/schemas/Pagination"
UserInstruction:
type: object
description: Text instruction item.
properties:
instruction:
type: string
description: Instruction text.
relativeStartTimeMs:
type: integer
description: Relative start time (milliseconds).
relativeEndTimeMs:
type: integer
description: Relative end time (milliseconds).
startTime:
type: number
description: Timeline start time (seconds).
endTime:
type: number
description: Timeline end time (seconds).
status:
type: string
description: Execution status.
Chapter:
type: object
description: Chapter item.
properties:
chapterId:
type: integer
description: Chapter ID.
title:
type: string
description: Chapter title.
brief:
type: string
description: Chapter brief.
actRange:
type: array
description: Act range [start, end].
items:
type: integer
startTime:
type: number
description: Chapter start time (seconds).
endTime:
type: number
description: Chapter end time (seconds).
chapterImage:
type: string
description: Chapter image URL.
QueryTravelStatusResponse:
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 send instructions, pause, or end), paused (paused on the server side; you can send instructions, resume, or end), failed (the Travel failed), completed (the Travel has ended; artifacts can be queried)."
enum:
- init
- pending
- running
- paused
- 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 text instructions; null when there is no data.
items:
$ref: "#/components/schemas/UserInstruction"
nullable: true
chapters:
type: array
description: The chapter list; null when chapter detection has not been triggered.
items:
$ref: "#/components/schemas/Chapter"
nullable: true
characterActions:
type: array
description: Acting does not support SDK action control; always returns an empty array.
items: {}
environmentActions:
type: array
description: Acting does not support SDK environment action control; always returns an empty array.
items: {}
QueryWorldBuildStatusResponse:
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.
nullable: true
name:
type: string
description: World name. Returned only when status=ready.
mode:
type: integer
description: Always 3 for Acting. Returned only when status=ready.
WorldDetailFirstFrameImage:
type: object
description: The required first-frame image at creation, echoed; returned in URL form only, base64 is not returned.
properties:
url:
type: string
description: First-frame image URL.
referenceType:
type: string
description: Reference type.
QueryWorldDetailResponse:
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 3 for Acting.
creationModel:
type: string
description: Always simple for Acting.
prompt:
type: string
description: The top-level prompt submitted at creation.
eventStyle:
type: string
description: A compatibility return field; when a compliant creation omits this field, the server usually maps it from uploadMode and echoes first_frame. It is not an Acting creation parameter, and clients should not send it back.
perspective:
type: string
description: Acting does not accept a perspective creation parameter; fixed to null.
nullable: true
uploadMode:
type: string
description: Fixed to first_frame.
resolution:
type: string
description: 480p / 720p; 480p if not passed at creation.
enum:
- 480p
- 720p
aspectRatio:
type: string
description: 9:16 / 16:9; 9:16 if not passed at creation.
enum:
- 9:16
- 16:9
layout:
type: string
description: Acting does not accept this creation parameter; fixed to null.
nullable: true
narrative:
type: string
description: Acting does not accept this creation parameter; fixed to null.
nullable: true
refWorldId:
type: string
description: The Acting encrypted reference World ID used for a derived creation; null if none.
nullable: true
firstFrameImage:
$ref: "#/components/schemas/WorldDetailFirstFrameImage"
inputImages:
type: string
description: Acting does not currently use this field.
nullable: true
sceneImage:
type: string
description: Acting does not use the scene/role image slots; fixed to null.
nullable: true
roleImage:
type: string
description: Acting does not use the scene/role image slots; fixed to null.
nullable: true
scenePrompt:
type: string
description: Acting does not use scene/role prompts; fixed to null.
nullable: true
rolePrompt:
type: string
description: Acting does not use scene/role prompts; fixed to null.
nullable: true
scriptList:
type: string
description: Acting does not support ScriptList; fixed to null.
nullable: true
previewUrl:
type: string
description: Currently fixed to null.
nullable: true
createdAt:
type: string
description: Creation time, in ISO 8601 format.
updatedAt:
type: string
description: Last update time, in ISO 8601 format.
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 3 for Acting.
previewUrl:
type: string
description: Usually null.
nullable: true
createdAt:
type: string
description: Creation time, in ISO 8601 format.
perspective:
type: string
description: Usually null.
nullable: true
creationModel:
type: string
description: Always simple.
uploadMode:
type: string
description: Fixed to first_frame.
QueryWorldListResponse:
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.
items:
$ref: "#/components/schemas/WorldListItem"
pagination:
$ref: "#/components/schemas/Pagination"