BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
HappyOyster-Directing-Query Referência da API de detalhes mundiais
Consulte o status atual, parâmetros de criação e informações retornáveis de ScriptList de um único Directing World. Para pesquisa de progresso de build, use o endpoint Query World Build Status.
Escopo
- Somente a chave API primária é suportada; Chaves de API temporárias não podem ser usadas (código de erro
403003). - Para pesquisa de progresso de construção, use Query World Build Status em vez disso.
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 Directing Open API
description: HappyOyster real-time directing (Directing) mode Open API. Create and manage Worlds, exchange experience credentials, enter rooms, send process instructions and script updates, pause/resume/rewind/end Travels, and query history and artifacts. The server side is called with the primary API Key over standard HTTPS REST. The client experiences the content in real time over an RTC channel using a temporary API Key and ticket.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: QwenCloud
security:
- BearerAuth: []
paths:
/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail:
get:
operationId: queryDirectingWorldDetail
summary: Query World Detail
description: "Query the current status, creation parameters, and returnable ScriptList information of a single Directing World. For build-progress polling, use the Query World Build Status endpoint. Authentication: only the primary API Key is supported; temporary API Keys cannot be used (error code 403003)."
parameters:
- 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.
- name: encryptedWorldId
in: query
required: true
schema:
type: string
description: A Directing encrypted World ID under the current primary account.
responses:
"200":
description: Query succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/QueryWorldDetailResponse"
examples:
scriptlist_detail:
summary: Query succeeded (script mode)
value:
code: 0
message: null
data:
encryptedWorldId: enc_a1b2****
name: Midnight Visitor
status: ready
mode: 2
creationModel: scriptlist
prompt: null
eventStyle: normal
perspective: null
uploadMode: null
resolution: 720p
layout: null
narrative: null
refWorldId: null
firstFrameImage:
url: https://cdn.happyoyster.com/frames/room.png
referenceType: default
inputImages: null
scriptList:
synopsis: Late at night, Su Li is startled awake by a knock at the door.
videoTitle: Midnight Visitor
subjects:
- label: "[character_1]"
name: Su Li
type: character
refImage:
url: https://cdn.happyoyster.com/subjects/suli.png
referenceType: default
acts:
- turn: 1
content: Rain beats against the window, and [character_1] is startled awake from sleep.
cameraType: Static
shotSize: Wide
cut: long-take
- turn: 2
content: "[character_1] walks toward the door, and the knocking sounds again outside."
cameraType: Push-in
shotSize: Close-up
cut: long-take
previewUrl: null
aspectRatio: null
createdAt: 2026-06-03T10:00:00Z
updatedAt: 2026-06-03T10:05:00Z
"400":
description: Request parameter error.
content:
application/json:
schema:
$ref: "#/components/schemas/HappyOysterErrorResponse"
"403":
description: Authentication or permission error.
content:
application/json:
schema:
$ref: "#/components/schemas/HappyOysterErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Query World detail
source: |-
curl --location 'https://maas.qwencloudapi.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
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 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: Image URL. Mutually exclusive with base64. Must be a valid http/https URL with a host, accessible by the server.
base64:
type: string
description: Image base64. Mutually exclusive with url. A complete data URI data:image/<subtype>;base64,<payload> is recommended.
referenceType:
type: string
description: Reference-image type. Defaults to 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 server-generated encrypted World ID.
status:
type: string
description: "Current creation status: generating/ready/failed."
enum:
- generating
- ready
- failed
firstFrame:
type: string
description: World first-frame URL; null before it is generated.
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: Whether there is more data.
DirectingCreateWorldRequest:
type: object
required:
- resolution
description: Directing Create World request body. Supports standard mode (creationModel=simple) and script mode (creationModel=scriptlist). simple mode requires prompt; scriptlist mode requires firstFrameImage and scriptList.
properties:
async:
type: boolean
description: "Whether to create asynchronously. Defaults to true. true: returns immediately; the World builds in the background. false: the server polls every 3 seconds for up to 120 seconds and returns when the build completes."
default: true
creationModel:
type: string
description: "Creation sub-mode. simple (standard mode, default): natural-language prompt, the server generates the full script. scriptlist (script mode): structured script provided by the user."
default: simple
enum:
- simple
- scriptlist
eventStyle:
type: string
description: Event style, used to select the script-generation template. Defaults to normal.
default: normal
enum:
- normal
- dramatic
- regular
refWorldId:
type: string
description: Derive a new creation from an existing Directing World. Must be a Directing encrypted World ID under the current primary account.
prompt:
type: string
description: World theme description; Chinese and English are supported. Non-empty, up to 2000 characters. Required for simple mode.
resolution:
type: string
description: Video resolution.
enum:
- 480p
- 720p
layout:
type: string
description: Camera movement style. Optional for simple mode.
enum:
- Stable
- Fast
- Calm
narrative:
type: string
description: Narrative style. Optional for simple mode.
enum:
- Calm
- Dramatic
- Normal
- Steady
firstFrameImage:
$ref: "#/components/schemas/FirstFrameImage"
inputImages:
type: array
description: Used for script generation and character reference images, up to 6 images, independent of firstFrameImage. Optional for simple mode.
items:
$ref: "#/components/schemas/FirstFrameImage"
scriptList:
$ref: "#/components/schemas/DirectingScriptList"
DirectingScriptList:
type: object
required:
- synopsis
- acts
description: Structured script. Required for scriptlist mode. Must include synopsis and a non-empty acts.
properties:
synopsis:
type: string
description: Story synopsis. Non-empty, up to 2000 characters.
videoTitle:
type: string
description: World name. Defaults to New World, up to 128 characters.
default: New World
scene:
type: string
description: Scene setting. Defaults to Static Shot, up to 64 characters.
default: Static Shot
style:
type: string
description: Visual style. Defaults to Stable, up to 64 characters.
default: Stable
speed:
type: string
description: Narrative pacing. Defaults to Steady, up to 64 characters.
default: Steady
language:
type: string
description: Script language. Defaults to en; pass zh for Chinese. Up to 64 characters.
default: en
setting:
type: string
description: Worldview or background setting. Up to 2000 characters.
soundtrack:
type: string
description: Soundtrack description. Up to 500 characters.
prologue:
type: string
description: Opening prologue. Up to 1000 characters.
videoTags:
type: array
description: Video tags. Up to 20 tags, each up to 32 characters.
items:
type: string
subjects:
type: array
description: Predefined subjects, up to 6.
items:
$ref: "#/components/schemas/DirectingSubject"
acts:
type: array
description: Beat-by-beat script, 1-45 entries, with all content totaling no more than 100000 characters.
items:
$ref: "#/components/schemas/DirectingAct"
DirectingSubject:
type: object
description: Script subject definition.
properties:
label:
type: string
description: References a subject in acts[].content. Formatted as [character_x].
name:
type: string
description: Human-readable name. Up to 64 characters.
type:
type: string
description: Subject type. Defaults to character.
enum:
- character
- animal
- creature
- narrator
default: character
refImage:
$ref: "#/components/schemas/FirstFrameImage"
gender:
type: string
description: Gender description. Up to 64 characters.
position:
type: string
description: On-screen position. Up to 64 characters.
ethnicity:
type: string
description: Ethnicity or race description. Up to 64 characters.
age:
type: string
description: Age description. Up to 64 characters.
appearance:
type: string
description: Appearance details. Up to 500 characters.
voice:
type: string
description: Voice, speaking rate, and volume description. Up to 200 characters.
DirectingAct:
type: object
required:
- content
description: Single beat script.
properties:
turn:
type: integer
description: Turn number. 1-45, no duplicates.
content:
type: string
description: Script for this beat. Non-empty, up to 2000 characters per beat.
cameraType:
type: string
description: Camera type. Defaults to Static.
enum:
- Static
- Tracking
- Pan Left
- Pan Right
- Tilt Up
- Tilt Down
- Push-in
- Pull-out
- POV Forward
- POV Look Down
- POV Look Up
- POV Turn Left
- POV Turn Right
default: Static
shotSize:
type: string
description: Shot size. Defaults to Medium.
enum:
- Wide
- Medium
- Close-up
default: Medium
cut:
type: string
description: Cut method. Defaults to long-take.
enum:
- long-take
- hard-cut
- cut-in
- cut-out
- cutaway
- cutback
- camera movement transition
default: long-take
DirectingDeleteWorldRequest:
type: object
required:
- encryptedWorldId
description: Delete World request body.
properties:
encryptedWorldId:
type: string
description: The Directing encrypted World ID to delete.
DeleteWorldResponse:
type: object
description: Delete World response.
properties:
code:
type: integer
description: Return code. 0 means success.
message:
type: string
description: Error message. null on success.
data:
type: object
description: Response data.
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.
DirectingEndTravelRequest:
type: object
required:
- encryptedTravelId
description: End Travel request body.
properties:
encryptedTravelId:
type: string
description: The Directing encrypted Travel ID to end.
failCode:
type: string
description: Failure end reason. When omitted, it is treated as a normal end. Currently only TRAVEL_NO_STREAM_AUTO_END is supported.
enum:
- TRAVEL_NO_STREAM_AUTO_END
userAgent:
type: string
description: SDK or client version identifier. A non-empty string.
EndTravelResponse:
type: object
description: End Travel response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
status:
type: string
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.
DirectingEnterTravelRequest:
type: object
required:
- ticket
description: Enter Travel (client) request body.
properties:
ticket:
type: string
description: An unexpired, unused single-use credential. Reusing the same ticket returns 401011.
maxExperienceTimeSec:
type: integer
description: Directing does not use this value; the successful response is still null. If passed, it can only be 60/90/120.
enum:
- 60
- 90
- 120
EnterTravelResponse:
type: object
description: Enter Travel response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
encryptedWorldId:
type: string
mode:
type: integer
description: Always 2 for Directing.
creationModel:
type: string
enum:
- simple
- scriptlist
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.
properties:
channelId:
type: string
appId:
type: string
token:
type: string
userId:
type: string
version:
type: string
description: The Directing enter-room version, fixed to storyV2.
aspectRatio:
type: string
description: Fixed to null for the Directing model.
noStreamAutoEndTimeoutSec:
type: integer
description: No-stream auto-end timeout in seconds, defaults to 30.
maxExperienceTimeSec:
type: integer
description: Fixed to null for the Directing model.
DirectingGetTravelCredentialRequest:
type: object
required:
- encryptedWorldId
description: Get Travel Credential request body.
properties:
encryptedWorldId:
type: string
description: A Directing World ID under the current primary account with status ready.
TravelCredentialResponse:
type: object
description: Get Travel Credential response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
ticket:
type: string
description: A single-use Travel credential prefixed with tk_. Valid for 1800 seconds.
expiresIn:
type: integer
description: Validity in seconds, fixed at 1800.
encryptedWorldId:
type: string
DirectingInstructTravelRequest:
type: object
required:
- encryptedTravelId
- content
description: Send Process Instruction request body. Only creationModel=simple is supported.
properties:
encryptedTravelId:
type: string
description: The Travel ID to control; creationModel must be simple.
content:
type: string
description: The text process instruction. Non-empty, up to 2000 characters.
clientRequestId:
type: string
description: Idempotency key for instruction retries. Recommended format [A-Za-z0-9_-]{1,32}.
userAgent:
type: string
InstructTravelResponse:
type: object
description: Send Process Instruction response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
content:
type: string
description: The accepted instruction text.
accepted:
type: boolean
DirectingTravelControlRequest:
type: object
required:
- encryptedTravelId
description: Travel control request body (pause/resume).
properties:
encryptedTravelId:
type: string
description: The encrypted Travel ID.
userAgent:
type: string
description: SDK or client version identifier.
TravelStatusResponse:
type: object
description: Travel status response (pause/resume).
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
status:
type: string
enum:
- paused
- running
DirectingRewindTravelRequest:
type: object
required:
- encryptedTravelId
- rewindToSec
description: Rewind Travel request body. The Travel must first enter paused.
properties:
encryptedTravelId:
type: string
rewindToSec:
type: number
description: The target video time, in seconds. Greater than or equal to 0; a multiple of 4 is recommended.
userAgent:
type: string
RewindTravelResponse:
type: object
description: Rewind Travel response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
status:
type: string
enum:
- running
resumedAtSec:
type: number
description: The actual number of seconds at which playback resumes.
actualRewindToSec:
type: number
description: The actual rewind landing point.
DirectingUpdateScriptRequest:
type: object
required:
- encryptedTravelId
- scriptList
description: Full script update request body. Only creationModel=scriptlist is supported.
properties:
encryptedTravelId:
type: string
description: creationModel must be scriptlist.
scriptList:
type: object
required:
- acts
description: Full script container. Only acts takes effect.
properties:
acts:
type: array
description: Complete act list. Must be exactly 45 entries, turn 1-45 contiguous and non-duplicated.
items:
$ref: "#/components/schemas/DirectingAct"
userAgent:
type: string
UpdateScriptResponse:
type: object
description: Full script update response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
accepted:
type: boolean
turnCount:
type: integer
description: Fixed at 45.
QueryTravelArtifactsResponse:
type: object
description: Query Travel Artifacts response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
composeStatus:
type: string
enum:
- ready
- partial
- processing
video:
type: object
properties:
original:
$ref: "#/components/schemas/VideoArtifact"
withWatermark:
$ref: "#/components/schemas/VideoArtifact"
withInstruction:
$ref: "#/components/schemas/VideoArtifact"
withInstructionAndWatermark:
$ref: "#/components/schemas/VideoArtifact"
VideoArtifact:
type: object
description: Single video artifact.
properties:
url:
type: string
description: Video URL; null when processing.
status:
type: string
enum:
- ready
- processing
- unavailable
resolution:
type: string
description: 720p when the original matches 720p; otherwise null.
durationSec:
type: integer
description: Video duration in seconds; null when it cannot be parsed.
QueryTravelListResponse:
type: object
description: Query Travel List response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
items:
type: array
items:
type: object
properties:
encryptedTravelId:
type: string
status:
type: string
enum:
- init
- pending
- running
- failed
- completed
mode:
type: integer
description: Always 2.
encryptedWorldId:
type: string
durationSec:
type: integer
createdAt:
type: string
endedAt:
type: string
pagination:
$ref: "#/components/schemas/Pagination"
QueryTravelStatusResponse:
type: object
description: Query Travel Status response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedTravelId:
type: string
status:
type: string
enum:
- init
- pending
- running
- paused
- failed
- completed
rtcStatus:
type: string
description: Server-side RTC streaming status.
updateTime:
type: string
description: Last update time, in ISO 8601 format.
userInstructions:
type: array
description: List of text instructions; null when there is no data.
items:
type: object
chapters:
type: array
description: Chapter list; null when chapter detection has not been triggered yet.
items:
type: object
characterActions:
type: array
description: Fixed as an empty array for the Directing model.
items:
type: object
environmentActions:
type: array
description: Fixed as an empty array for the Directing model.
items:
type: object
QueryWorldBuildStatusResponse:
type: object
description: Query World Build Status response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedWorldId:
type: string
status:
type: string
enum:
- generating
- ready
- failed
firstFrame:
type: string
description: World first-frame URL; null when not yet generated.
name:
type: string
description: World name. Returned only when status=ready.
mode:
type: integer
description: Always 2 for Directing. Returned only when status=ready.
QueryWorldDetailResponse:
type: object
description: Query World Detail response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
encryptedWorldId:
type: string
name:
type: string
status:
type: string
enum:
- generating
- ready
- failed
mode:
type: integer
description: Always 2 for Directing.
creationModel:
type: string
enum:
- simple
- scriptlist
prompt:
type: string
description: The Prompt used in simple mode; null for scriptlist.
eventStyle:
type: string
enum:
- normal
- dramatic
- regular
perspective:
type: string
description: Usually null for the Directing model.
uploadMode:
type: string
description: Usually null for a Directing World.
resolution:
type: string
enum:
- 480p
- 720p
layout:
type: string
narrative:
type: string
refWorldId:
type: string
firstFrameImage:
type: object
description: The first-frame image at creation; base64 is not returned.
inputImages:
type: array
description: Reference images persisted in simple mode; null for scriptlist.
scriptList:
type: object
description: Has a value only for scriptlist; null when parsing fails.
previewUrl:
type: string
description: Fixed to null.
aspectRatio:
type: string
description: Fixed to null for the Directing model.
createdAt:
type: string
updatedAt:
type: string
QueryWorldListResponse:
type: object
description: Query World List response.
properties:
code:
type: integer
message:
type: string
data:
type: object
properties:
items:
type: array
items:
type: object
properties:
encryptedWorldId:
type: string
name:
type: string
status:
type: string
enum:
- generating
- ready
- failed
mode:
type: integer
description: Always 2.
perspective:
type: string
description: Usually null.
creationModel:
type: string
enum:
- simple
- scriptlist
uploadMode:
type: string
description: Usually null.
createdAt:
type: string
pagination:
$ref: "#/components/schemas/Pagination"