BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
HappyOyster-Acting-Enter Referência da API de viagens
O cliente usa o ticket para criar uma viagem real e obter a configuração de adesão do RTC, a versão da capacidade de atuação e a proporção do jogador. Uma chamada bem-sucedida cria a Viagem.
Escopo
Antes de ligar, confirme o seguinte:
- Autenticação: A Chave API primária não é necessária; o
ticketconclui a validação de entrada na sala. - Pré-requisitos: O
ticketé obtido em Obter credencial de viagem, não expirado e não utilizado, e seu status mundial éready. - Chamador: Chamado pelo seu cliente.
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/travels/enter-travel:
post:
operationId: enterActingTravel
summary: Enter Travel (Client)
description: "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. Authentication: The primary API Key is not required; the ticket completes the enter-room validation. The ticket is obtained from Get Travel Credential, unexpired and unused, and its World status is ready. Called by the client."
x-codeSamples:
- lang: curl
label: cURL - Enter travel (client)
source: |-
curl --location 'https://maas.qwencloudapi.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}"
}'
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. 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.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/EnterTravelRequest"
responses:
"200":
description: Entered successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterTravelResponse"
examples:
success:
summary: Entered successfully
value:
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
"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"