BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
HappyOyster-Directing-Create Referência Mundial da API
Crie um mundo de direção em tempo real. Suporta modo padrão (prompt de linguagem natural) e modo de script (ScriptList estruturado); a API retorna imediatamente um World ID criptografado, o World constrói de forma assíncrona em segundo plano e o cliente pesquisa o progresso da construção até que seja concluído.
Escopo
- Somente a chave API primária é suportada; Chaves de API temporárias não podem ser usadas (código de erro
403003). - O modo assíncrono é recomendado:
async=true, a API retorna imediatamenteencryptedWorldId; enquete Consultar status de construção do mundo para o progresso. - Este endpoint só pode criar um Mundo Diretivo. Você não precisa passar
mode(o servidor escreve2; passando um valor diferente de2retorna400000).creationModelsuportasimpleescriptlist; a versão de entrada é fixada emstoryV2easpectRatioemaxExperienceTimeSecestão fixados emnull.
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:
post:
operationId: createDirectingWorld
summary: Create World
description: "Create a real-time directing World. Supports standard mode (creationModel=simple, natural-language prompt) and script mode (creationModel=scriptlist, structured ScriptList). The API immediately returns an encrypted World ID, and the World builds asynchronously in the background; the client polls the Query World Build Status endpoint for progress. Authentication: only the primary API Key is supported; temporary API Keys cannot be used (error code 403003). This endpoint can only create a Directing World. You do not need to pass mode (the server writes 2; passing a value other than 2 returns 400000). creationModel supports simple and scriptlist; the enter-room version is fixed to storyV2, and aspectRatio and maxExperienceTimeSec are fixed to null."
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/DirectingCreateWorldRequest"
responses:
"200":
description: World created successfully or the async creation was accepted.
content:
application/json:
schema:
$ref: "#/components/schemas/CreateWorldResponse"
examples:
async_generating:
summary: Async create accepted
value:
code: 0
message: null
data:
encryptedWorldId: enc_a1b2****
status: generating
firstFrame: null
"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 - Standard mode · plain text
source: |-
curl --location 'https://maas.qwencloudapi.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"creationModel": "simple",
"eventStyle": "normal",
"prompt": "First-person (POV) interactive video: the camera simulates my own eyes, locked on a white Maltese puppy directly in front of me — white chef\u2019s hat, black-buttoned chef\u2019s coat. Soft home-kitchen background, warm light, the puppy\u2019s gaze always facing the camera.",
"resolution": "720p",
"layout": "Stable",
"narrative": "Calm"
}'
- lang: curl
label: cURL - Standard mode · text + reference image
source: |-
curl --location 'https://maas.qwencloudapi.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"creationModel": "simple",
"eventStyle": "normal",
"prompt": "A café by the window. A young woman with long black hair, wearing a beige turtleneck sweater, sits sideways, her left hand propping up her chin as she gazes at the rain-speckled glass window. On the wooden table sits a cup of steaming dark coffee. Outside, warm-yellow street lamps glow in the rainy night; indoors, a single pendant lamp. A quiet rainy night.",
"resolution": "720p",
"inputImages": [
{
"url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
"referenceType": "default"
}
]
}'
- lang: curl
label: cURL - Script mode
source: |-
curl --location 'https://maas.qwencloudapi.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"creationModel": "scriptlist",
"eventStyle": "normal",
"resolution": "720p",
"firstFrameImage": {
"url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
"referenceType": "default"
},
"scriptList": {
"videoTitle": "Su Nian · Sitting with You for a While Tonight",
"synopsis": "The young girl Su Nian sits at a light-colored desk facing the camera, chatting with you slowly and helping you let go of the day.",
"subjects": [
{
"label": "[character_1]",
"name": "Su Nian",
"type": "character",
"gender": "female",
"age": "young girl",
"ethnicity": "East Asian",
"appearance": "medium-length straight black hair with a side part, a rounded face, a cream-white knit top, anime style, clean lines",
"position": "center of the frame, seated at a light-colored desk",
"voice": "gentle girlish voice, slightly slow pace, moderate volume"
}
],
"acts": [
{
"turn": 1,
"content": "[character_1] sits at the light-colored desk facing the camera, leaning slightly forward, eyes curving as she softly says, \u201cHey, I\u2019ll sit with you for a while again tonight, let\u2019s chat slowly.\u201d",
"cameraType": "Push-in",
"shotSize": "Medium",
"cut": "long-take"
},
{
"turn": 2,
"content": "[character_1] folds her hands on the desk, nods gently, and says, \u201cLet\u2019s set aside all the worries of the day for now.\u201d",
"cameraType": "Static",
"shotSize": "Medium",
"cut": "long-take"
},
{
"turn": 3,
"content": "[character_1] tilts her head slightly, looking at the camera with a gentle expression, and asks, \u201cHow was your day? Are you okay, are you tired?\u201d",
"cameraType": "Static",
"shotSize": "Medium",
"cut": "long-take"
}
]
}
}'
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"