Référence de l'API HappyOyster-Adventure-Create World - Alibaba Cloud Model Studio

Créer un Monde d'exploration. Créer un Monde à partir d'une invite en langage naturel et d'une première image obligatoire ; l'API retourne immédiatement un ID chiffré de Monde, 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 Adventure. Avant d'appeler, 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é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 Adventure. Vous n'avez pas besoin de passer mode (le serveur écrit 1 ; passer une valeur autre que 1 retourne 400000). creationModel est toujours simple, uploadMode est fixé à first_frame, et la version d'entrée en salle est fixée à wanderV2.

Requête HTTP

Singapore

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

Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

Chine (Pékin)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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-adventure/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-adventure/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "perspective": "third_person",
    "prompt": "Third-person tracking shot: a rider in a black snowsuit and black helmet drives a black snowmobile into the distance, the track kicking up fine snow. Ahead lies a snow-covered coniferous forest; farther off, steep sunlit rock cliffs of snow mountains under a blue sky with white clouds. Clear winter sky, strong snow highlights, open and crisp.",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png"
    }
}'

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-adventure/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "perspective": "third_person",
    "prompt": "Third-person tracking shot: a rider in a black snowsuit and black helmet drives a black snowmobile into the distance, the track kicking up fine snow. Ahead lies a snow-covered coniferous forest; farther off, steep sunlit rock cliffs of snow mountains under a blue sky with white clouds. Clear winter sky, strong snow highlights, open and crisp.",
    "firstFrameImage": {
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    }
}'

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.

perspective string (Obligatoire)

Perspective. Valeurs autorisées :

first_person : première personne
third_person : troisième personne

L'omission de ce champ retourne 400000.

prompt string (Requis)

Description du thème du Monde ; le chinois et l'anglais sont pris en charge. Non vide, jusqu'à 2000 caractères. Si manquant, vide ou trop long, retourne 400000.

creationModel string (Facultatif)

Sous-mode de création. La valeur par défaut est simple ; Adventure prend uniquement en charge simple.

uploadMode string (Facultatif)

Mode de téléchargement d'image. La valeur par défaut est first_frame ; Adventure prend uniquement en charge first_frame.

refWorldId string (Facultatif)

Dériver une nouvelle création à partir d'un Monde Adventure existant. Doit être un ID chiffré de Monde Adventure sous le compte principal actuel ; un Monde provenant d'un autre modèle ou d'un autre compte principal retourne 403001.

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 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 d'image de référence. 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
    }
}

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.

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 construction) ou ready ; peut également être failed lorsqu'une construction synchrone échoue.

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 :

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 un ticket à usage unique.
Interroger les détails du Monde : interroger toutes les métadonnées de création.