Skip to main content

Referencia de la API de HappyOyster-Directing-Create World

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).
  • 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
  • EE. UU. (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worldsReemplace {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)
  • 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": "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"
}'
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)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 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.
eventStyle no se consume en la creación de scriptlist; no lo pase.
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.
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:
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.
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:
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 integerCódigo de retorno. 0 indica éxito; un valor distinto de cero es un código de error.
message stringMensaje de error. null en caso de éxito.
data objectDatos de respuesta. null en caso de fallo.

Propiedades

encryptedWorldId stringID 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 stringEstado actual de la creación:
  • generating: construyendo
  • ready: listo
  • failed: error de construcción
firstFrame stringURL 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:

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: