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).- Obtenir la clé API principale : Obtenir et configurer une clé API.
-
Mode d'appel : Le mode asynchrone est recommandé.
- Mode asynchrone (par défaut) :
async=true, l'API retourne immédiatementencryptedWorldId; 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.
- Mode asynchrone (par défaut) :
-
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 écrit2; passer une valeur autre que2retourne400000).creationModelprend en chargesimple(mode standard, par défaut) etscriptlist(mode script) ; la version d'entrée en salle est fixée àstoryV2, etaspectRatioainsi quemaxExperienceTimeSecsont 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 |
|
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 :
| |
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 :
| |
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 :
| |
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 :
| |
layout string (Facultatif)Style de mouvement de la caméra (comment la caméra bouge et comment elle coupe brusquement). Valeurs autorisées :
| |
narrative string (Facultatif)Style narratif (densité du drame et intensité de l'émotion). Valeurs autorisées :
| |
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 :
Propriétés url string (Conditionnellement obligatoire)URL de l'image de la première image. Contraintes :
string (Conditionnellement obligatoire)Image de la première image base64. Contraintes :
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 :
Propriétés url string (Conditionnellement obligatoire)URL de l'image. Contraintes :
string (Conditionnellement obligatoire)Image base64. Contraintes :
string (Facultatif)Type d'image de référence. Par défaut default. |
Mode script (creationModel=scriptlist)
Paramètres de la requête |
|
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 :
| |
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 :
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 :
| |
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 :
Propriétés url string (Conditionnellement obligatoire)URL de l'image de la première image. Contraintes :
string (Conditionnellement obligatoire)Image de la première image base64. Contraintes :
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 :
Propriétés de subjects[] 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 :
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.
Propriétés de refImage 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.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.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 :
Propriétés de acts[] 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 :
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 :
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 :
|
Paramètres de réponse |
|
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 :
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,
actsest 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
creationModelsont 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 :instruct: envoyer des instructions de processus textuelles à un voyage en cours ; mode standard uniquement.pause: mettre en pause le voyage.resume: reprendre la lecture.rewind: rembobiner jusqu'à un point temporel spécifié ; nécessite une mise en pause préalable.end: terminer le voyage.update-script: remplacer entièrement le script ; mode script uniquement.
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 :
- Interroger l'état de construction du Monde : interroger toutes les 3–5 secondes jusqu'à ce que le Monde passe à l'état
ready. - Une fois que le Monde est passé à l'état
ready, appelez Obtenir les informations d'identification de voyage pour les échanger contre unticketà usage unique. - Interroger les détails du monde : interroger l'intégralité des métadonnées de création et la ScriptList.