Skip to main content

Référence de l'API HappyOyster-Directing-Create World

Créer un monde de mise en scène en temps réel. Prend en charge le mode standard (prompt en langage naturel) et le mode script (ScriptList structuré) ; l'API retourne immédiatement un ID de monde chiffré, le monde se construit de manière asynchrone en arrière-plan, et le client interroge la progression de la construction jusqu'à son achèvement.

Scope

Créer un monde de réalisation. Avant d'effectuer l'appel, confirmez les points suivants :
  • Authentification : Seule la clé API principale est prise en charge ; les clés API temporaires ne peuvent pas être utilisées (code d'erreur 403003).
  • Mode d'appel : Le mode asynchrone est recommandé.
    • Mode asynchrone (par défaut) : async=true, l'API retourne immédiatement encryptedWorldId ; interrogez Interroger l'état de construction du Monde pour suivre la progression.
    • Mode synchrone : async=false, le serveur interroge en interne (toutes les 3s, jusqu'à 120s) et retourne un résultat lorsque la construction est terminée ; en cas de délai d'attente dépassé, il revient au mode asynchrone et le client continue d'interroger.
  • Restrictions du point de terminaison : Ce point de terminaison peut uniquement créer un monde de réalisation. Vous n'avez pas besoin de passer mode (le serveur écrit 2 ; passer une valeur autre que 2 retourne 400000). creationModel prend en charge simple (mode standard, par défaut) et scriptlist (mode script) ; la version d'entrée en salle est fixée à storyV2, et aspectRatio ainsi que maxExperienceTimeSec sont fixés à null.

Requête HTTP

  • Singapore
  • États-Unis (Virginie)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worldsRemplacez {WorkspaceId} par votre véritable ID d'espace de travail.

Mode standard (creationModel=simple)

Paramètres de la requête

  • Mode standard · texte brut (création asynchrone)
  • Mode standard · texte + image de référence (création asynchrone)
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(Requis)Type de contenu de la requête. Ce paramètre doit être défini sur application/json.
Authorization string (Requis)Authentification par clé API. Seule la clé API principale est prise en charge ; elle commence par sk-, par ex. sk-xxx. Elle est généralement configurée comme variable d'environnement $DASHSCOPE_API_KEY. Une clé API temporaire (commençant par st-) renvoie 403003.
Corps de la requête
async boolean (Optionnel)Indique s'il faut créer de manière asynchrone. La valeur par défaut est true :
  • true : retourne immédiatement ; le Monde se construit en arrière-plan, et le client interroge Interroger l'état de construction du Monde.
  • false : le serveur interroge toutes les 3 secondes pendant un maximum de 120 secondes et retourne un résultat lorsque la construction est terminée ; en cas de délai d'attente dépassé, il retourne tout de même generating, et le client effectue ensuite ses propres interrogations.
creationModel string (Facultatif)Sous-mode de création ; passez simple pour le mode standard (par défaut). Vous fournissez un prompt en langage naturel, et le serveur génère le script complet de 45 temps, la première image (que vous pouvez fournir) et les images de référence des personnages. Une fois le monde créé, vous pouvez appeler les points de terminaison de contrôle suivants pendant la phase de voyage :
  • instruct : envoyer des instructions de processus textuelles
  • pause : pause
  • resume : reprendre
  • rewind : rembobiner
  • end : fin
Voir Notes supplémentaires pour une description de chaque point de terminaison.
eventStyle string (Facultatif)S'applique uniquement à creationModel=simple : sélectionne le modèle de génération de script. La valeur par défaut est normal. Valeurs autorisées :
  • normal : style régulier / standard (par défaut). Complète 4 à 5 actes selon l'intention de l'utilisateur à un rythme relativement constant, sans forcer les conflits, les renversements ou un climax en trois actes.
  • dramatic : style dramatique / conflictuel. Génère un script sur une structure en trois actes d'environ 180 secondes : accroche d'ouverture, conflit croissant, tournant, résolution climactique ; pour une performance ouverte, il organise les renversements par genre (mystère / thriller / retour en force, etc.), avec un rythme plus dense et un drame plus fort.
  • regular : valeur héritée, conservée uniquement pour la compatibilité ascendante avec les entrées historiques ; le serveur l'analyse comme normal. Ne l'utilisez pas dans les nouveaux appels.
refWorldId string (Facultatif)Dériver une nouvelle création à partir d'un monde de réalisation existant. Il doit s'agir d'un ID de monde de réalisation chiffré sous le compte principal actuel ; un monde provenant d'un autre modèle ou d'un autre compte principal retourne 403001.
prompt string (Requis)Description du thème du monde ; le chinois et l'anglais sont pris en charge. Non vide, jusqu'à 2000 caractères.
resolution string (Obligatoire)Résolution vidéo. Valeurs autorisées :
  • 480p
  • 720p
layout string (Facultatif)Style de mouvement de la caméra (comment la caméra bouge et comment elle coupe brusquement). Valeurs autorisées :
  • Stable : caméra stable, peu de mouvements, privilégiant les plans-séquences continus avec des coupes rares
  • Fast : caméra rapide, forte dynamique, avec des coupes franches plus denses / zooms rapides / changements d'échelle de plan
  • Calm : entre les deux, une caméra sobre qui n'est ni précipitée ni agressive
narrative string (Facultatif)Style narratif (densité du drame et intensité de l'émotion). Valeurs autorisées :
  • Calm : peu d'événements, privilégiant l'atmosphère et une progression lente
  • Dramatic : événements denses, avec des réactions / renversements / obstacles plus marqués et une tension élevée
  • Normal : densité narrative régulière, un niveau intermédiaire
  • Steady : rythme régulier sans accumulation de climax, proche de Normal
firstFrameImage object (Facultatif)Lorsqu'elle est fournie, elle est réutilisée directement comme première image du monde, en ignorant la génération de première image par l'IA. url et base64 sont mutuellement exclusifs (choisissez-en un). Contraintes de l'image :
  • Format : JPG / JPEG / PNG / WebP
  • Taille : strictement inférieure à 6 Mo par image
  • Rapport d'aspect : doit être paysage, largeur / hauteur de 1.5–2.0 (le rapport du cadre suit cette image)
  • Sécurité du contenu : l'échec de la vérification de sécurité du contenu ou des droits d'auteur / IP renvoie 403004 / 403005

Propriétés

url string (Conditionnellement obligatoire)URL de l'image de la première image. Contraintes :
  • Doit être une URL http / https valide avec un hôte, accessible par le serveur
  • Le format réel, la taille et le rapport d'aspect de la première image sont validés après le stockage
  • Une requête asynchrone peut d'abord retourner generating, puis le Monde passe à l'état failed en raison d'un échec de validation de l'image
base64 string (Conditionnellement obligatoire)Image de la première image base64. Contraintes :
  • Un URI de données complet data:image/<subtype>;base64,<payload> est recommandé
  • Le format, la taille et le rapport d'aspect de la première image sont validés de manière synchrone au point d'entrée de création
referenceType string (Facultatif)Type d'image de référence. Par défaut default.
inputImages array (Facultatif)Utilisé pour la génération de scripts et les images de référence de personnages, jusqu'à 6 images, indépendamment de firstFrameImage. Pour chaque élément du tableau, url et base64 sont mutuellement exclusifs (choisissez-en un). Contraintes de l'image :
  • Format : JPG / JPEG / PNG / WebP
  • Taille : strictement inférieure à 6 Mo par image
  • Rapport d'aspect : doit être paysage, largeur / hauteur de 1.5–2.0 (le rapport du cadre suit cette image)
  • Sécurité du contenu : l'échec de la vérification de sécurité du contenu ou des droits d'auteur / IP renvoie 403004 / 403005

Propriétés

url string (Conditionnellement obligatoire)URL de l'image. Contraintes :
  • Doit être une URL http / https valide avec un hôte, accessible par le serveur
  • Le format, la taille et le rapport d'aspect réels sont validés après le stockage
  • Une requête asynchrone peut d'abord retourner generating, puis le Monde passe à l'état failed en raison d'un échec de validation de l'image
base64 string (Conditionnellement obligatoire)Image base64. Contraintes :
  • Un URI de données complet data:image/<subtype>;base64,<payload> est recommandé
  • Le format, la taille et le rapport d'aspect sont validés de manière synchrone au point d'entrée de création
referenceType string (Facultatif)Type d'image de référence. Par défaut default.

Mode script (creationModel=scriptlist)

Paramètres de la requête

  • Mode script (création asynchrone)
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(Requis)Type de contenu de la requête. Ce paramètre doit être défini sur application/json.
Authorization string (Requis)Authentification par clé API. Seule la clé API principale est prise en charge ; elle commence par sk-, par ex. sk-xxx. Elle est généralement configurée comme variable d'environnement $DASHSCOPE_API_KEY. Une clé API temporaire (commençant par st-) renvoie 403003.
Corps de la requête
async boolean (Optionnel)Indique s'il faut créer de manière asynchrone. La valeur par défaut est true :
  • true : retourne immédiatement ; le Monde se construit en arrière-plan, et le client interroge Interroger l'état de construction du Monde.
  • false : le serveur interroge toutes les 3 secondes pendant un maximum de 120 secondes et retourne un résultat lorsque la construction est terminée ; en cas de délai d'attente dépassé, il retourne tout de même generating, et le client effectue ensuite ses propres interrogations.
creationModel string (Facultatif)Sous-mode de création ; passez scriptlist pour le mode script. Vous fournissez le script structuré, et le serveur ne génère plus de script — il se contente de l'assembler et de le persister. Une fois le monde créé, vous pouvez appeler les points de terminaison de contrôle suivants pendant la phase de voyage :
  • update-script : remplacer entièrement le script
  • pause : pause
  • resume : reprendre
  • rewind : rembobiner
  • end : fin
instruct (envoyer des instructions de processus textuelles) n'est pas pris en charge. Voir Notes supplémentaires pour une description de chaque point de terminaison.
eventStyle n'est pas utilisé lors de la création de scriptlist ; ne le transmettez pas.
refWorldId string (Facultatif)Dériver une nouvelle création à partir d'un monde de réalisation existant. Il doit s'agir d'un ID de monde de réalisation chiffré sous le compte principal actuel ; un monde provenant d'un autre modèle ou d'un autre compte principal retourne 403001.
resolution string (Obligatoire)Résolution vidéo. Valeurs autorisées :
  • 480p
  • 720p
firstFrameImage object (Requis)Une référence d'image réutilisée directement comme première image du Monde. url et base64 sont mutuellement exclusifs (choisissez-en un). Contraintes de l'image :
  • Format : JPG / JPEG / PNG / WebP
  • Taille : strictement inférieure à 6 Mo par image
  • Rapport d'aspect : doit être paysage, largeur / hauteur de 1.5–2.0 (le rapport du cadre suit cette image)
  • Sécurité du contenu : l'échec de la vérification de sécurité du contenu ou des droits d'auteur / IP renvoie 403004 / 403005

Propriétés

url string (Conditionnellement obligatoire)URL de l'image de la première image. Contraintes :
  • Doit être une URL http / https valide avec un hôte, accessible par le serveur
  • Le format réel, la taille et le rapport d'aspect de la première image sont validés après le stockage
  • Une requête asynchrone peut d'abord retourner generating, puis le Monde passe à l'état failed en raison d'un échec de validation de l'image
base64 string (Conditionnellement obligatoire)Image de la première image base64. Contraintes :
  • Un URI de données complet data:image/<subtype>;base64,<payload> est recommandé
  • Le format, la taille et le rapport d'aspect de la première image sont validés de manière synchrone au point d'entrée de création
referenceType string (Facultatif)Type d'image de référence. Par défaut default.
scriptList object (Obligatoire)Script structuré. Doit inclure synopsis et un élément acts non vide.

Propriétés

synopsis string (Obligatoire)Synopsis de l'histoire. Non vide, jusqu'à 2000 caractères.videoTitle string (Facultatif)Nom du monde. Par défaut New World, jusqu'à 128 caractères.scene string (Optionnel)Paramètre de la scène. La valeur par défaut est Static Shot, jusqu'à 64 caractères.style string (Optionnel)Style visuel. Par défaut Stable, jusqu'à 64 caractères.speed string (Optionnel)Rythme narratif. La valeur par défaut est Steady, jusqu'à 64 caractères.language string (Facultatif)Langue du script. La valeur par défaut est en (anglais) ; passez zh pour le chinois. Jusqu'à 64 caractères.setting string (Facultatif)Vision du monde ou contexte. Jusqu'à 2000 caractères.soundtrack string (Facultatif)Description de la bande sonore. Jusqu'à 500 caractères.prologue string (Facultatif)Prologue d'ouverture. Jusqu'à 1000 caractères.videoTags array<string> (Facultatif)Tags vidéo. Jusqu'à 20 tags, chacun jusqu'à 32 caractères.subjects array<object> (Facultatif)Sujets prédéfinis, jusqu'à 6. Chaque élément du tableau contient les propriétés suivantes :
label string (Optionnel)Référence un sujet dans acts[].content. Formaté sous la forme [character_x], attribué dans l'ordre du tableau par défaut.name string (Optionnel)Nom lisible par l'homme, non rendu sous forme de texte à l'écran. Jusqu'à 64 caractères.type string (Optionnel)Type de sujet. La valeur par défaut est character. Détermine l'apparence du sujet et la manière dont les autres propriétés sont renseignées. Valeurs autorisées :
  • character : personnage humain (par défaut). Renseignez gender / position / ethnicity / age / appearance comme pour une personne.
  • animal : animal réel (chat, chien, cheval, etc.). Utilisez l'espèce au lieu du genre et la sous-espèce / race au lieu de l'origine ethnique.
  • creature : créature non humaine / fantastique (dragon, monstre, extraterrestre, etc.). Renseignez également une apparence non humaine.
  • narrator : narrateur / voix off. Voix uniquement, n'apparaît pas à l'écran ; renseignez voice et aucune image de référence n'est générée.
refImage object (Facultatif)Image de référence du sujet ; url et base64 sont mutuellement exclusifs (choisissez-en un), et l'image doit être strictement inférieure à 6 Mo.
url string (Conditionnellement obligatoire)URL de l'image de référence du sujet.base64 string (Conditionnellement obligatoire)Image de référence du sujet base64.referenceType string (Facultatif)Type d'image de référence. Par défaut default.
gender string (Facultatif)Description du genre. Jusqu'à 64 caractères.position string (Facultatif)Position à l'écran. Jusqu'à 64 caractères.ethnicity string (Facultatif)Description de l'ethnie ou de la race. Jusqu'à 64 caractères.age string (Optionnel)Description de l'âge. Jusqu'à 64 caractères.appearance string (Facultatif)Détails de l'apparence. Jusqu'à 500 caractères.voice string (Optionnel)Description de la voix, du débit de parole et du volume. Jusqu'à 200 caractères.
acts array<object> (Obligatoire)Script temps par temps, de 1 à 45 entrées, l'ensemble des content ne devant pas dépasser 100000 caractères au total. Chaque élément du tableau contient les propriétés suivantes :
turn int (Optionnel)Numéro de tour. 1–45, sans doublons, incrémenté à partir de 1 dans l'ordre du tableau par défaut.content string (Obligatoire)Script pour ce temps. Non vide, jusqu'à 2000 caractères par temps ; peut référencer des sujets avec [character_x].cameraType string (Facultatif)Type de caméra (comment la caméra filme). La valeur par défaut est Static. Valeurs autorisées :
  • Static : caméra fixe, sans zoom ni pivotement (par défaut). L'échelle de plan est contrôlée par shotSize : large / moyen / serré
  • Tracking : plan de suivi. La caméra suit le sujet en maintenant la distance de suivi
  • Pan Left : la caméra reste fixe, panoramique gauche
  • Pan Right : la caméra reste fixe, panoramique droite
  • Tilt Up : la caméra s'incline vers le haut
  • Tilt Down : la caméra s'incline vers le bas
  • Push-in : zoom avant optique / physique, le cadre se rapproche progressivement
  • Pull-out : zoom arrière, le cadre s'élargit progressivement
  • POV Forward : première personne, la caméra représente les yeux, avançant vers l'avant
  • POV Look Down : première personne regardant vers le bas
  • POV Look Up : première personne regardant vers le haut
  • POV Turn Left : première personne tournant la tête vers la gauche
  • POV Turn Right : première personne tournant la tête vers la droite
shotSize string (Facultatif)Échelle de plan. La valeur par défaut est Medium. Détermine le niveau de détail que ce temps peut porter ; modifiez l'échelle de plan via les coupes, et ne décrivez pas à la fois le corps entier et le bout des doigts dans le même temps. Valeurs autorisées :
  • Wide : plan large / plan général, incluant le corps entier et sa relation avec l'environnement. Adapté aux placements, au positionnement et à la mise en scène spatiale ; ne décrivez pas les micro-expressions ou le bout des doigts.
  • Medium : plan moyen (par défaut), posture et gestes du haut du corps. Adapté aux dialogues et aux actions quotidiennes ; ne décrivez pas les déplacements de pieds ou les opérations fines des mains.
  • Close-up : gros plan, un visage / une main / un accessoire. Adapté aux expressions et aux détails clés ; ne décrivez pas les mouvements du corps entier.
Combinaison avec les coupes : pour voir plus de détails, faites d'abord un cut-in vers un Close-up, puis un cut-out pour revenir à un plan large ; utilisez long-take pour la plupart des temps afin de maintenir la même échelle de plan et d'éviter les sauts d'échelle répétés.cut string (Optionnel)Méthode de coupe (comment ce temps est enchaîné). La valeur par défaut est long-take. Valeurs autorisées :
  • long-take : aucune coupe, continuité du plan précédent. Valeur par défaut et la plus stable
  • hard-cut : coupe franche, basculement instantané vers un autre plan. À utiliser pour les dialogues en champ / contrechamp
  • cut-in : couper vers un plan plus serré, par ex. Medium → Close-up. À utiliser pour voir les détails et insérer des interactions manuelles
  • cut-out : couper vers un plan plus large, par ex. Close-up → Medium / Wide
  • cutaway : coupe brève vers un détail hors du plan principal
  • cutback : retour au sujet principal depuis un cutaway. Ne peut suivre qu'un cutaway
  • camera movement transition : relier deux segments par un mouvement rapide de la caméra plutôt que par une coupe franche

Paramètres de réponse

  • Création asynchrone
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}
code integerCode de retour. 0 indique un succès ; une valeur non nulle correspond à un code d'erreur.
message stringMessage d'erreur. null en cas de succès.
data objectDonnées de réponse. null en cas d'échec.

Propriétés

encryptedWorldId stringID de monde chiffré, retourné en modes synchrone et asynchrone. Cette valeur est utilisée pour les requêtes ultérieures d'état de construction, les requêtes de détails du monde et l'échange d'un identifiant d'expérience.status stringStatut de création actuel :
  • generating : en cours de construction
  • ready : prêt
  • failed : échec de la construction
firstFrame stringURL de la première image du Monde ; null avant sa génération.

Notes supplémentaires

  • Comptage des caractères : Les limites « jusqu'à N caractères » dans ce document sont comptées par caractère (caractères Unicode), qu'il s'agisse de chinois ou d'anglais — les caractères chinois, les lettres anglaises, les chiffres, les espaces et la ponctuation comptent chacun pour 1 caractère.
  • Exigences de soumission de ScriptList : Lors de la création d'un monde, acts est limité à 45 entrées mais n'est pas tenu d'être exactement de 45 ; les 45 entrées complètes ne sont requises que lors de l'appel à update-script pendant le voyage.
  • Points de terminaison de contrôle du voyage : Les noms de points de terminaison listés sous creationModel sont des points de terminaison côté serveur pouvant être appelés pendant la phase de voyage après la création du monde, et non des valeurs d'énumération pour l'entrée de ce point de terminaison. Leurs significations sont les suivantes :

Codes d'erreur

Si l'appel du modèle échoue et renvoie une erreur, consultez Codes d'erreur HappyOyster pour la résoudre.

Étapes suivantes

Après une création réussie, vous pouvez :