Créer un Monde de jeu de rôle. Créer un Monde à partir d'une invite en langage naturel et d'une image de première frame requise ; l'API retourne immédiatement un ID de Monde chiffré (encryptedWorldId), 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 Acting. 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 Acting. Vous n'avez pas besoin de transmettre mode (le serveur écrit 3 ; transmettre une valeur autre que 3 renvoie 400000). creationModel est toujours simple, uploadMode est fixé à first_frame, et la version d'entrée dans la salle est fixée à actingV2.
Requête HTTP
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
États-Unis (Virginie)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
Paramètres de la requête | Image de la première frame (asynchrone)curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"prompt": "A blonde girl with twin tails, a white bow, and a golden crescent crown on her forehead; a white shirt with a navy sailor collar and a blue bow tie, and a blue-and-white argyle short skirt. Her right hand holds up a yellow sticky note that reads \"Good night\". Behind her are a deep-red velvet curtain and a cluster of flowers. Facing the camera, an anime-realistic blend, warm indoor lighting.",
"resolution": "480p",
"aspectRatio": "9:16",
"firstFrameImage": {
"url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc5.png",
"referenceType": "default"
}
}'
Base64 de l'image de la première frame (asynchrone)curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"prompt": "A relaxed conversation on the living-room sofa, with the character naturally looking toward the camera",
"resolution": "480p",
"aspectRatio": "9:16",
"firstFrameImage": {
"base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
"referenceType": "default"
}
}'
|
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 (Facultatif) 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. La valeur par défaut est simple ; Acting prend uniquement en charge simple. |
prompt string (Requis) Une description en langage naturel du personnage, de la scène et de l'objectif de performance. Non vide, jusqu'à 2000 caractères. Si manquant, vide ou trop long, renvoie 400000. |
uploadMode string (Facultatif) Mode de téléchargement d'image. La valeur par défaut est first_frame ; Acting prend uniquement en charge first_frame. |
resolution string (Facultatif) Résolution vidéo. La valeur par défaut est 480p. Valeurs autorisées : |
aspectRatio string (Facultatif) Rapport d'aspect du flux, qui détermine également l'orientation de la première image ; il est recommandé de maintenir la cohérence entre les deux. La valeur par défaut est 9:16. Valeurs autorisées :
9:16 (portrait) : une première image en mode portrait est recommandée16:9 (paysage) : une première image en mode paysage est recommandée Autrement dit, pour un flux en portrait (9:16), transmettez une première image en portrait, et pour un flux en paysage (16:9), transmettez une première image en paysage. La valeur par défaut est 9:16 ; lorsque le mode paysage est nécessaire, vous devez explicitement transmettre aspectRatio=16:9. |
refWorldId string (Facultatif) Dériver une nouvelle création à partir d'un Monde Acting existant. Doit être un ID de Monde Acting chiffré sous le compte principal actuel ; un Monde provenant d'un autre modèle ou d'un autre compte principal renvoie 403001. |
firstFrameImage object (Requis) Une référence d'image réutilisée comme première image du Monde. url et base64 sont mutuellement exclusifs (choisir l'un ou l'autre). Contraintes de l'image :
- Format : JPG / JPEG / PNG / WebP
- Taille : strictement inférieure à 6 Mo par image
- Rapport d'aspect : lorsque
aspectRatio=9:16, largeur / hauteur est de 0.5–0.667 ; lorsque aspectRatio=16:9, il est de 1.5–2.0
- 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 requis) URL de l'image de la première frame. Mutuellement exclusif avec base64 (choisir l'un ou l'autre). 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 requis) Base64 de l'image de la première frame. Mutuellement exclusif avec url (choisir l'un ou l'autre). 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 de référence de la première image. La valeur par défaut est default, et elle est actuellement utilisée comme default. |
Paramètres de réponse | Création asynchrone{
"code": 0,
"message": null,
"data": {
"encryptedWorldId": "enc_a1b2****",
"status": "generating",
"firstFrame": null
}
}
Échec de la requête{
"code": 400000,
"message": "Invalid request parameters.",
"data": null
}
|
code integer Code de retour. 0 indique un succès ; une valeur non nulle correspond à un code d'erreur. |
message string Message d'erreur. null en cas de succès ; un message d'erreur lisible par l'homme en cas d'échec. |
data object Données de réponse. null en cas d'échec. Propriétés encryptedWorldId string L'ID de Monde chiffré généré par le serveur. Retourné dans les modes synchrone et asynchrone ; utilisé pour l'interrogation ultérieure de l'état de construction, les requêtes de détails et l'échange d'informations d'identification de voyage. status string Statut de création actuel :
generating : en cours de constructionready : prêtfailed : échec de la construction firstFrame string URL de la première image du Monde ; null avant sa génération. |
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 :