Referencia de la API de HappyOyster-Directing-Create World - Alibaba Cloud Model Studio

Crea un Mundo de dirección en tiempo real. Admite modo estándar (prompt en lenguaje natural) y modo guion (ScriptList estructurado); la API devuelve inmediatamente un ID de Mundo cifrado, el Mundo se construye de forma asíncrona en segundo plano y el cliente sondea el progreso de la construcción hasta que finaliza.

Ámbito

Cree un Mundo de Dirección. Antes de realizar la llamada, confirme lo siguiente:

Autenticación: Solo se admite la API Key principal; no se pueden utilizar API Keys temporales (código de error 403003).
- Obtenga la API Key principal: Obtener y configurar una API Key.
Modo de llamada: Se recomienda el modo asíncrono.
- Modo asíncrono (predeterminado): async=true, la API devuelve inmediatamente encryptedWorldId; sondee Consultar estado de construcción del mundo para verificar el progreso.
- Modo síncrono: async=false, el servidor sondea internamente (cada 3s, hasta 120s) y devuelve cuando finaliza la construcción; si se agota el tiempo de espera, vuelve al modo asíncrono y el cliente continúa sondeando.
Restricciones del endpoint: Este endpoint solo puede crear un Mundo de Dirección. No es necesario pasar mode (el servidor escribe 2; pasar un valor distinto de 2 devuelve 400000). creationModel admite simple (modo estándar, predeterminado) y scriptlist (modo guion); la versión de entrada a la sala está fijada en storyV2, y aspectRatio y maxExperienceTimeSec están fijados en null.

Solicitud HTTP

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

EE. UU. (Virginia)

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Modo estándar (`creationModel=simple`)

Parámetros de solicitud

Modo estándar · texto sin formato (creación asíncrona)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.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's hat, black-buttoned chef's coat. Soft home-kitchen background, warm light, the puppy's gaze always facing the camera.",
    "resolution": "720p",
    "layout": "Stable",
    "narrative": "Calm"
}'

Modo estándar · texto + imagen de referencia (creación asíncrona)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.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"
        }
    ]
}'

Content-Typestring(Requerido)

Tipo de contenido de la solicitud. Este parámetro debe establecerse en application/json.

Authorization string (Requerido)

Autenticación mediante API Key. Solo se admite la API Key principal; comienza con sk-, p. ej., sk-xxx. Normalmente se configura como la variable de entorno $DASHSCOPE_API_KEY. Una API Key temporal (que comienza con st-) devuelve 403003.

Cuerpo de la solicitud

async boolean (Opcional)

Indica si se debe crear de forma asíncrona. El valor predeterminado es true:

true: devuelve inmediatamente; el mundo se construye en segundo plano y el cliente sondea Consultar estado de construcción del mundo.
false: el servidor sondea cada 3 segundos durante un máximo de 120 segundos y devuelve cuando finaliza la construcción; si se agota el tiempo de espera, aún devuelve generating, y el cliente continúa sondeando por su cuenta.

creationModel string (Opcional)

Submodo de creación; pase simple para el modo estándar (predeterminado). Usted proporciona un prompt en lenguaje natural y el servidor genera el guion completo de 45 planos, el primer fotograma (que usted puede proporcionar) y las imágenes de referencia de personajes. Después de crear el Mundo, puede llamar a los siguientes endpoints de control durante la fase de Viaje:

instruct: enviar instrucciones de proceso de texto
pause: pausar
resume: reanudar
rewind: rebobinar
end: finalizar

Consulte Notas adicionales para obtener una descripción de cada endpoint.

eventStyle string (Opcional)

Aplica solo a creationModel=simple: selecciona la plantilla de generación de guion. El valor predeterminado es normal. Valores permitidos:

normal: estilo regular / estándar (predeterminado). Completa 4–5 actos según la intención del usuario a un ritmo relativamente constante, sin forzar conflictos, giros o un clímax de tres actos.
dramatic: estilo dramático / de conflicto. Genera un guion sobre un esqueleto de tres actos de aproximadamente 180 segundos: gancho inicial, conflicto creciente, punto de inflexión, resolución climática; para representaciones abiertas organiza giros por género (misterio / suspenso / regreso, etc.), con un ritmo más denso y un drama más fuerte.
regular: valor heredado, conservado solo por compatibilidad con versiones anteriores de entradas históricas; el servidor lo analiza como normal. No lo use en nuevas llamadas.

refWorldId string (Opcional)

Derive una nueva creación de un Mundo de Dirección existente. Debe ser un ID de Mundo cifrado de Dirección bajo la cuenta principal actual; un Mundo de otro modelo u otra cuenta principal devuelve 403001.

prompt string (Obligatorio)

Descripción del tema del mundo; se admiten chino e inglés. No vacío, hasta 2000 caracteres.

resolution string (Obligatorio)

Resolución de video. Valores permitidos:

480p
720p

layout string (Opcional)

Estilo de movimiento de cámara (cómo se mueve la cámara y qué tan bruscos son los cortes). Valores permitidos:

Stable: cámara estable, poco movimiento, favorece tomas largas continuas con cortes esporádicos
Fast: cámara rápida, gran impulso, con cortes bruscos más densos / zooms rápidos / saltos de tamaño de plano
Calm: entre ambos, una cámara contenida que no es apresurada ni agresiva

narrative string (Opcional)

Estilo narrativo (qué tan denso es el drama y qué tan fuerte es la emoción). Valores permitidos:

Calm: pocos eventos, favorece la atmósfera y una progresión lenta
Dramatic: eventos densos, con reacciones / giros / obstáculos más pronunciados y alta tensión
Normal: densidad narrativa regular, un nivel medio
Steady: ritmo uniforme sin acumular clímax, similar a Normal

firstFrameImage object (Opcional)

Cuando se proporciona, se reutiliza directamente como el primer fotograma del Mundo, omitiendo la generación de primer fotograma por IA. url y base64 son mutuamente excluyentes (elija uno). Restricciones de imagen:

Formato: JPG / JPEG / PNG / WebP
Tamaño: estrictamente menor que 6 MB por imagen
Relación de aspecto: debe ser horizontal, ancho / alto de 1.5–2.0 (la relación del fotograma sigue esta imagen)
Seguridad del contenido: si falla la verificación de seguridad del contenido o de derechos de autor / propiedad intelectual, devuelve 403004 / 403005

Propiedades

url string (Condicionalmente obligatorio)

URL de la imagen del primer fotograma. Restricciones:

Debe ser una URL http / https válida con un host, accesible por el servidor
El formato, tamaño y relación de aspecto del primer fotograma reales se validan después del almacenamiento
Una solicitud asíncrona puede devolver primero generating, luego el mundo entra en failed debido a un fallo en la validación de la imagen

base64 string (Condicionalmente obligatorio)

Base64 de la imagen del primer fotograma. Restricciones:

Se recomienda un URI de datos completo data:image/<subtype>;base64,<payload>
El formato, tamaño y relación de aspecto del primer fotograma se validan sincrónicamente en el punto de entrada de creación

referenceType string (Opcional)

Tipo de imagen de referencia. El valor predeterminado es default.

inputImages array (Opcional)

Se utiliza para la generación de guiones e imágenes de referencia de personajes, hasta 6 imágenes, independiente de firstFrameImage. Para cada elemento del arreglo, url y base64 son mutuamente excluyentes (elija uno). Restricciones de imagen:

Formato: JPG / JPEG / PNG / WebP
Tamaño: estrictamente menor que 6 MB por imagen
Relación de aspecto: debe ser horizontal, ancho / alto de 1.5–2.0 (la relación del fotograma sigue esta imagen)
Seguridad del contenido: si falla la verificación de seguridad del contenido o de derechos de autor / propiedad intelectual, devuelve 403004 / 403005

Propiedades

url string (Condicionalmente obligatorio)

URL de la imagen. Restricciones:

Debe ser una URL http / https válida con un host, accesible por el servidor
El formato, tamaño y relación de aspecto reales se validan después del almacenamiento
Una solicitud asíncrona puede devolver primero generating, luego el mundo entra en failed debido a un fallo en la validación de la imagen

base64 string (Condicionalmente obligatorio)

Base64 de la imagen. Restricciones:

Se recomienda un URI de datos completo data:image/<subtype>;base64,<payload>
El formato, tamaño y relación de aspecto se validan sincrónicamente en el punto de entrada de creación

referenceType string (Opcional)

Tipo de imagen de referencia. El valor predeterminado es default.

Modo de guion (`creationModel=scriptlist`)

Parámetros de solicitud

Modo guion (creación asíncrona)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.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",
    "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, \"Hey, I'll sit with you for a while again tonight, let's chat slowly.\"",
                "cameraType": "Push-in",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] folds her hands on the desk, nods gently, and says, \"Let's set aside all the worries of the day for now.\"",
                "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, \"How was your day? Are you okay, are you tired?\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            }
        ]
    }
}'

Content-Typestring(Requerido)

Tipo de contenido de la solicitud. Este parámetro debe establecerse en application/json.

Authorization string (Requerido)

Cuerpo de la solicitud

async boolean (Opcional)

Indica si se debe crear de forma asíncrona. El valor predeterminado es true:

true: devuelve inmediatamente; el mundo se construye en segundo plano y el cliente sondea Consultar estado de construcción del mundo.
false: el servidor sondea cada 3 segundos durante un máximo de 120 segundos y devuelve cuando finaliza la construcción; si se agota el tiempo de espera, aún devuelve generating, y el cliente continúa sondeando por su cuenta.

creationModel string (Opcional)

Submodo de creación; pase scriptlist para el modo de guion. Usted proporciona el guion estructurado y el servidor ya no genera un guion, solo lo ensambla y persiste. Después de crear el Mundo, puede llamar a los siguientes endpoints de control durante la fase de Viaje:

update-script: reemplazar completamente el guion
pause: pausar
resume: reanudar
rewind: rebobinar
end: finalizar

instruct (enviar instrucciones de proceso de texto) no es compatible. Consulte Notas adicionales para obtener una descripción de cada endpoint.

Nota

eventStyle no se consume en la creación de scriptlist; no lo pase.

refWorldId string (Opcional)

resolution string (Obligatorio)

Resolución de video. Valores permitidos:

480p
720p

firstFrameImage object (Requerido)

Una referencia de imagen reutilizada directamente como el primer fotograma del mundo. url y base64 son mutuamente excluyentes (elija uno). Restricciones de imagen:

Formato: JPG / JPEG / PNG / WebP
Tamaño: estrictamente menor que 6 MB por imagen
Relación de aspecto: debe ser horizontal, ancho / alto de 1.5–2.0 (la relación del fotograma sigue esta imagen)
Seguridad del contenido: si falla la verificación de seguridad del contenido o de derechos de autor / propiedad intelectual, devuelve 403004 / 403005

Propiedades

url string (Condicionalmente obligatorio)

URL de la imagen del primer fotograma. Restricciones:

Debe ser una URL http / https válida con un host, accesible por el servidor
El formato, tamaño y relación de aspecto del primer fotograma reales se validan después del almacenamiento
Una solicitud asíncrona puede devolver primero generating, luego el mundo entra en failed debido a un fallo en la validación de la imagen

base64 string (Condicionalmente obligatorio)

Base64 de la imagen del primer fotograma. Restricciones:

Se recomienda un URI de datos completo data:image/<subtype>;base64,<payload>
El formato, tamaño y relación de aspecto del primer fotograma se validan sincrónicamente en el punto de entrada de creación

referenceType string (Opcional)

Tipo de imagen de referencia. El valor predeterminado es default.

scriptList object (Obligatorio)

Guion estructurado. Debe incluir synopsis y un elemento acts no vacío.

Propiedades

synopsis string (Obligatorio)

Sinopsis de la historia. No vacía, hasta 2000 caracteres.

videoTitle string (Opcional)

Nombre del mundo. Valor predeterminado New World, hasta 128 caracteres.

scene string (Opcional)

Configuración de la escena. El valor predeterminado es Static Shot, hasta 64 caracteres.

style string (Opcional)

Estilo visual. Valor predeterminado Stable, hasta 64 caracteres.

speed string (Opcional)

Ritmo narrativo. El valor predeterminado es Steady, hasta 64 caracteres.

language string (Opcional)

Idioma del guion. El valor predeterminado es en (inglés); pase zh para chino. Hasta 64 caracteres.

setting string (Opcional)

Cosmovisión o configuración de fondo. Hasta 2000 caracteres.

soundtrack string (Opcional)

Descripción de la banda sonora. Hasta 500 caracteres.

prologue string (Opcional)

Prólogo de apertura. Hasta 1000 caracteres.

videoTags array<string> (Opcional)

Etiquetas de video. Hasta 20 etiquetas, cada una de hasta 32 caracteres.

subjects array<object> (Opcional)

Sujetos predefinidos, hasta 6. Cada elemento del arreglo contiene las siguientes propiedades:

Propiedades de subjects[]

label string (Opcional)

Hace referencia a un sujeto en acts[].content. Formateado como [character_x], asignado en orden de arreglo de forma predeterminada.

name string (Opcional)

Nombre legible por humanos, no se muestra como texto en pantalla. Hasta 64 caracteres.

type string (Opcional)

Tipo de sujeto. El valor predeterminado es character. Determina la apariencia del sujeto y cómo se completan las demás propiedades. Valores permitidos:

character: personaje humano (predeterminado). Complete gender / position / ethnicity / age / appearance como para una persona.
animal: animal real (gato, perro, caballo, etc.). Use especie en lugar de género y subespecie / raza en lugar de etnia.
creature: criatura no humana / fantástica (dragón, monstruo, alienígena, etc.). Complete también para una apariencia no humana.
narrator: narrador / voz en off. Solo voz, no aparece en pantalla; complete voice y no se generará ninguna imagen de referencia.

refImage object (Opcional)

Imagen de referencia del sujeto; url y base64 son mutuamente excluyentes (elija uno), y la imagen debe ser estrictamente menor a 6 MB.

Propiedades de refImage

url string (Condicionalmente obligatorio)

URL de la imagen de referencia del sujeto.

base64 string (Condicionalmente obligatorio)

Base64 de la imagen de referencia del sujeto.

referenceType string (Opcional)

Tipo de imagen de referencia. El valor predeterminado es default.

gender string (Opcional)

Descripción de género. Hasta 64 caracteres.

position string (Opcional)

Posición en pantalla. Hasta 64 caracteres.

ethnicity string (Opcional)

Descripción de etnia o raza. Hasta 64 caracteres.

age string (Opcional)

Descripción de edad. Hasta 64 caracteres.

appearance string (Opcional)

Detalles de apariencia. Hasta 500 caracteres.

voice string (Opcional)

Descripción de voz, velocidad de habla y volumen. Hasta 200 caracteres.

acts array<object> (Obligatorio)

Guion plano por plano, 1–45 entradas, con todo content sumando no más de 100000 caracteres. Cada elemento del arreglo contiene las siguientes propiedades:

Propiedades de acts[]

turn int (Opcional)

Número de turno. 1–45, sin duplicados, incrementando desde 1 en orden de arreglo de forma predeterminada.

content string (Obligatorio)

Guion para este plano. No vacío, hasta 2000 caracteres por plano; puede hacer referencia a sujetos con [character_x].

cameraType string (Opcional)

Tipo de cámara (cómo graba la cámara). El valor predeterminado es Static. Valores permitidos:

Static: cámara fija en su lugar, sin acercamiento ni giro (predeterminado). El tamaño del plano se controla mediante shotSize: amplio / medio / cercano
Tracking: plano de seguimiento. La cámara sigue al sujeto, manteniendo la distancia de seguimiento
Pan Left: la cámara permanece fija, paneando a la izquierda
Pan Right: la cámara permanece fija, paneando a la derecha
Tilt Up: la cámara se inclina hacia arriba
Tilt Down: la cámara se inclina hacia abajo
Push-in: acercamiento óptico/físico, el encuadre se aproxima gradualmente
Pull-out: alejar, el encuadre se amplía gradualmente
POV Forward: primera persona, la cámara son los ojos, caminando hacia adelante
POV Look Down: primera persona mirando hacia abajo
POV Look Up: primera persona mirando hacia arriba
POV Turn Left: primera persona girando a la izquierda para mirar
POV Turn Right: primera persona girando a la derecha para mirar

shotSize string (Opcional)

Tamaño del plano. El valor predeterminado es Medium. Determina cuánto detalle puede contener este plano; cambie el tamaño del plano mediante cortes y no describa tanto el cuerpo completo como las puntas de los dedos en el mismo plano. Valores permitidos:

Wide: plano general / completo, incluye el cuerpo entero y su relación con el entorno. Adecuado para bloqueos, posicionamiento y puesta en escena espacial; no describa microexpresiones ni puntas de los dedos.
Medium: plano medio (predeterminado), postura y gestos de la parte superior del cuerpo. Adecuado para diálogos y acciones cotidianas; no describa movimientos de pies ni operaciones finas de manos.
Close-up: primer plano, un rostro / una mano / un objeto. Adecuado para expresiones y detalles clave; no describa movimientos de cuerpo completo.

Combinación con cortes: para ver más detalle, primero haga cut-in a Close-up, luego cut-out de vuelta a un plano amplio; use long-take para la mayoría de los planos a fin de mantener el mismo tamaño de plano y evitar saltar entre tamaños de plano repetidamente.

cut string (Opcional)

Método de corte (cómo entra este plano). El valor predeterminado es long-take. Valores permitidos:

long-take: sin corte, continúa desde la toma anterior. Predeterminado y el más estable
hard-cut: corte brusco, cambio instantáneo a otra toma. Úselo para diálogos de plano / contraplano
cut-in: corte a un tamaño de plano más cercano, p. ej., Medium → Close-up. Úselo para ver detalles e introducir interacciones manuales
cut-out: corte a un plano más amplio, p. ej., Close-up → Medium / Wide
cutaway: corte breve a un detalle fuera de la línea principal
cutback: vuelve al sujeto principal desde un cutaway. Solo puede seguir a un cutaway
camera movement transition: conecta dos segmentos con un movimiento rápido de cámara en lugar de un corte brusco

Parámetros de respuesta

Creación asíncrona

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}

code integer

Código de retorno. 0 indica éxito; un valor distinto de cero es un código de error.

message string

Mensaje de error. null en caso de éxito.

data object

Datos de respuesta. null en caso de fallo.

Propiedades

encryptedWorldId string

ID de Mundo cifrado, devuelto tanto en modos síncronos como asíncronos. Este valor se utiliza para consultas posteriores de estado de compilación, consultas de detalles del Mundo e intercambio de credenciales de experiencia.

status string

Estado actual de la creación:

generating: construyendo
ready: listo
failed: error de construcción

firstFrame string

URL del primer fotograma del mundo; null antes de que se genere.

Notas adicionales

Conteo de caracteres: Los límites de "hasta N caracteres" en este documento se cuentan por carácter (caracteres Unicode), independientemente de si es chino o inglés; los caracteres chinos, letras inglesas, dígitos, espacios y signos de puntuación cuentan cada uno como 1 carácter.
Requisitos de envío de ScriptList: Al crear un Mundo, acts está limitado a 45 entradas pero no se requiere que sean exactamente 45; las 45 entradas completas solo son necesarias al llamar a update-script durante el Viaje.
Endpoints de control de Viaje: Los nombres de endpoints listados bajo creationModel son endpoints del lado del servidor que pueden llamarse durante la fase de Viaje después de crear el Mundo, no valores de enumeración para la entrada de este endpoint. Sus significados son los siguientes:
- instruct: enviar instrucciones de proceso de texto a un Viaje en curso; solo modo estándar.
- pause: pausar el Viaje.
- resume: reanudar la reproducción.
- rewind: rebobinar a un punto de tiempo específico; requiere pausar primero.
- end: finalizar el Viaje.
- update-script: reemplazar completamente el guion; solo modo de guion.

Códigos de error

Si la llamada al modelo falla y devuelve un error, consulte Códigos de error de HappyOyster para resolverlo.

Siguientes pasos

Después de crear con éxito, puede:

Consultar estado de construcción del mundo: sondee cada 3–5 segundos hasta que el mundo entre en ready.
Después de que el mundo entre en ready, llame a Obtener credencial de viaje para canjearla por un ticket de un solo uso.
Consultar detalles del mundo: consulta los metadatos completos de la creación y ScriptList.

Ámbito

Solicitud HTTP

Singapore

EE. UU. (Virginia)

Modo estándar (creationModel=simple)

Parámetros de solicitud

Modo estándar · texto sin formato (creación asíncrona)

Modo estándar · texto + imagen de referencia (creación asíncrona)

Cuerpo de la solicitud

Modo de guion (creationModel=scriptlist)

Parámetros de solicitud

Modo guion (creación asíncrona)

Cuerpo de la solicitud

Parámetros de respuesta

Creación asíncrona

Notas adicionales

Códigos de error

Siguientes pasos

Modo estándar (`creationModel=simple`)

Modo de guion (`creationModel=scriptlist`)