Skip to main content

HappyOyster-Acting-Query Travel Status API Reference

Interroger le cycle de vie du Travel Acting, le statut du streaming côté serveur, les instructions textuelles envoyées et les informations de chapitre ; vous pouvez également signaler simultanément le heartbeat de pull-stream ou de lecture du client.

Scope

Interroger le cycle de vie du Travel Acting, le statut de streaming côté serveur, les instructions textuelles envoyées et les informations de chapitre ; vous pouvez également signaler le signal de présence de pull-stream ou de lecture du client en même temps. Avant d'effectuer l'appel, confirmez les points suivants :
  • Authentification : La clé API principale n'est pas requise ; la clé principale ou une clé API temporaire peut l'appeler. Pour savoir comment les obtenir, voir Obtenir les identifiants d'authentification.
  • Prérequis : Interrogez avec l'encryptedTravelId renvoyé par Enter Travel.
  • Appelant : Votre serveur ou votre client peut l'appeler. Il est recommandé d'effectuer une interrogation toutes les 2 à 5 secondes.

Requête HTTP

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

Paramètres de la requête

  • Interroger le statut du Travel
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/status?encryptedTravelId={encryptedTravelId}&clientStreamStatus=PLAYING&clientStreamStatusTimeMs=1788940800000' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
Authorization string (Requis)Authentification par clé API. La clé API principale n'est pas requise ; la clé principale ou une clé API temporaire peut l'appeler.
  • Clé API principale : commence par sk-, par ex. sk-xxx.
  • Clé API temporaire : commence par st-, par exemple st-xxx.
Paramètres de requête
encryptedTravelId string (Obligatoire)L'ID de Travel chiffré Acting. Renvoyé par Enter Travel.
clientStreamStatus string (Facultatif)Le statut de pull-stream RTC ou de lecture du client, insensible à la casse. Les valeurs non reconnues sont ignorées. Valeurs autorisées :
  • DISCONNECTED : non connecté ou a quitté le canal
  • CONNECTING : connexion au canal RTC
  • CONNECTED : connecté, mais la lecture n'a pas commencé ou la première image n'est pas arrivée
  • PLAYING : le flux distant a été reçu et est en cours de rendu
  • BUFFERING : mise en mémoire tampon
  • PAUSED : le client a mis la lecture en pause ; cela ne signifie pas la pause côté serveur
  • RECONNECTING : reconnexion
clientStreamStatusTimeMs long (Facultatif)L'horodatage en millisecondes du changement d'état du client. Utilisé conjointement avec clientStreamStatus.

Paramètres de réponse

  • Travel en cours
  • Échec du Travel
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-09-09T08:30:00Z",
        "userInstructions": [
            {
                "instruction": "Greet with a smile and ask how my day is going",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "Greeting",
                "brief": "The character smiles at the camera and starts the conversation",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/acting_ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}
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

encryptedTravelId stringIdentifiant de voyage chiffré.status stringStatut du cycle de vie du Travel :
  • init : initialisation des ressources de session
  • pending : en file d'attente ou en attente de ressources de service
  • running : en cours d'exécution ; vous pouvez envoyer des instructions textuelles, mettre en pause ou terminer
  • paused : mis en pause côté serveur ; vous pouvez envoyer des instructions textuelles, reprendre ou terminer
  • failed : le Travel a échoué ; voir errorCode / errorMessage pour la raison
  • completed : le Travel est terminé ; les artefacts peuvent être interrogés
rtcStatus stringStatut de streaming RTC côté serveur ; différent du clientStreamStatus signalé par le client.updateTime stringHeure de dernière mise à jour, au format ISO 8601.userInstructions arrayLa liste des instructions textuelles ; null lorsqu'il n'y a pas de données. Chaque élément contient instruction (texte de l'instruction), relativeStartTimeMs / relativeEndTimeMs (millisecondes relatives), startTime / endTime (secondes de la chronologie) et status (statut d'exécution).chapters arrayLa liste des chapitres ; null lorsque la détection de chapitres n'a pas été déclenchée. Chaque élément contient chapterId, title, brief, actRange, startTime, endTime et chapterImage.characterActions array<string> | nullActing ne prend pas en charge le contrôle d'action SDK ; renvoie un tableau vide ; null lorsque failed.environmentActions array<string> | nullActing ne prend pas en charge le contrôle d'action d'environnement SDK ; renvoie un tableau vide ; null lorsque failed.errorCode stringRenvoyé uniquement lorsque status=failed ; un code de raison d'échec structuré. Voir Error codes pour les valeurs.errorMessage stringRenvoyé avec errorCode ; une description de l'échec en anglais. Effectuez une branche sur errorCode, et non sur errorMessage.

États préalables et notes d'appel

  • Une interrogation toutes les 2–5 secondes est recommandée.
  • running et paused permettent tous deux d'appeler Send Process Instruction ; l'envoi d'une instruction dans l'état paused ne reprend pas automatiquement le Travel.
  • Ce point de terminaison ne retourne pas mode, aspectRatio, playUrl, bgmUrl, ni sessionId ; la configuration du streaming et l'orientation du lecteur sont basées sur la réponse de Enter Travel.
  • clientStreamStatus est le signal de présence de lecture côté client, et rtcStatus est le statut de streaming côté serveur ; ils ne sont pas interchangeables.
  • Acting ne prend pas en charge le sendCommand SDK ; ne créez pas de contrôles de direction ou d'action basés sur les deux tableaux d'actions vides.
  • failed est un état terminal et aucune vidéo ne sera produite ; affichez la raison de l'échec basée sur errorCode, et ne l'affichez pas comme « pas encore terminé ».

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

Lorsque le Travel est running ou paused :