Skip to main content

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

Interroger le statut actuel, les paramètres de création et les informations ScriptList retournables d'un seul Monde Directing. Pour le polling de la progression de la construction, utilisez le point de terminaison Query World Build Status.

Scope

Interroger le statut actuel, les paramètres de création et les informations ScriptList retournables d'un seul Monde Directing. 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).
  • Prérequis : Interroger avec l'encryptedWorldId retourné par Create World. Pour le sondage de la progression de la construction, utiliser Query World Build Status.
  • Appelant : Appelé par votre serveur.

Requête HTTP

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

Paramètres de la requête

  • Interroger le détail du World
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
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.
Paramètres de requête
encryptedWorldId string (Requis)Un ID de Monde chiffré Directing sous le compte principal actuel. Retourné par Créer un monde.

Paramètres de réponse

  • Requête réussie (mode script)
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "Midnight Visitor",
        "status": "ready",
        "mode": 2,
        "creationModel": "scriptlist",
        "prompt": null,
        "eventStyle": "normal",
        "perspective": null,
        "uploadMode": null,
        "resolution": "720p",
        "layout": null,
        "narrative": null,
        "refWorldId": null,
        "firstFrameImage": {
            "url": "https://cdn.happyoyster.com/frames/room.png",
            "referenceType": "default"
        },
        "inputImages": null,
        "scriptList": {
            "synopsis": "Late at night, Su Li is startled awake by a knock at the door.",
            "videoTitle": "Midnight Visitor",
            "subjects": [
                {
                    "label": "[character_1]",
                    "name": "Su Li",
                    "type": "character",
                    "refImage": {
                        "url": "https://cdn.happyoyster.com/subjects/suli.png",
                        "referenceType": "default"
                    }
                }
            ],
            "acts": [
                {
                    "turn": 1,
                    "content": "Rain beats against the window, and [character_1] is startled awake from sleep.",
                    "cameraType": "Static",
                    "shotSize": "Wide",
                    "cut": "long-take"
                },
                {
                    "turn": 2,
                    "content": "[character_1] walks toward the door, and the knocking sounds again outside.",
                    "cameraType": "Push-in",
                    "shotSize": "Close-up",
                    "cut": "long-take"
                }
            ]
        },
        "previewUrl": null,
        "aspectRatio": null,
        "createdAt": "2026-06-03T10:00:00Z",
        "updatedAt": "2026-06-03T10:05:00Z"
    }
}
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 chiffré du World.name stringNom du World.status stringStatut de la construction : generating / ready / failed.mode integerToujours 2 pour la mise en scène.creationModel stringsimple / scriptlist ; détermine quels points de terminaison de contrôle le Voyage peut appeler.prompt stringLe Prompt utilisé lors de la création en mode simple ; fixé à null pour scriptlist.eventStyle stringLe style d'événement à la création : normal / dramatic / regular.perspective nullGénéralement null pour le modèle Directing.uploadMode nullGénéralement null pour un Monde Directing.resolution string480p / 720p.layout stringLe style de mouvement de caméra pour le mode simple ; généralement null lorsqu'il n'est pas passé ou pour scriptlist.narrative stringLe style narratif pour le mode simple ; généralement null lorsqu'il n'est pas passé ou pour scriptlist.refWorldId stringL'ID de Monde de référence chiffré utilisé pour une création dérivée.firstFrameImage objectL'image de la première frame à la création ; base64 n'est pas retourné dans la réponse.inputImages arrayLes images de référence persistantes lors de la création en mode simple ; scriptlist n'accepte pas ce champ, il est donc généralement null.scriptList objectA une valeur uniquement pour un Monde scriptlist ; null lorsque l'analyse du script structuré échoue. Contient synopsis, videoTitle, scene, style, speed, language, setting, soundtrack, prologue, videoTags, subjects (avec label/name/type/refImage, etc.), et acts (retourné intégralement selon le contenu stocké, avec turn/content/cameraType/shotSize/cut).previewUrl nullActuellement fixé à null.aspectRatio nullFixé à null pour le modèle de mise en scène.createdAt stringHeure de création, au format ISO 8601.updatedAt stringHeure de dernière mise à jour, au format ISO 8601.

États préalables et notes d'appel

  • Ce point de terminaison peut interroger un Monde generating, ready ou failed.
  • Il ne renvoie pas le champ async de la requête de création.
  • Les champs d'image retournent uniquement l'URL et referenceType, et ne retournent jamais base64. Les inputImages pour le mode simple sont persistants en tant qu'images de référence et peuvent être retournés dans le détail ; scriptlist n'accepte pas ce champ.
  • Lorsque scriptList est analysé normalement, la structure stockée complète est retournée, et acts est retourné intégralement selon le contenu stocké ; en cas d'échec de l'analyse, scriptList=null est retourné, et un acts vide n'est pas utilisé pour indiquer un échec d'analyse.
  • L'interrogation d'un World provenant d'un autre modèle, d'un autre compte principal, ou d'un World supprimé retourne toujours 403001, sans révéler si la ressource existe.

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