Skip to main content

Referencia de la API HappyOyster-Directing-Query Travel Status

Consulte el ciclo de vida del Travel de Directing, el estado de streaming en el servidor, las instrucciones de texto ejecutadas y la información de capítulos; también puede reportar el heartbeat de pull-stream o reproducción del cliente al mismo tiempo.

Ámbito

Consulte el ciclo de vida del Travel de Directing, el estado de streaming en el servidor, las instrucciones de texto ejecutadas y la información de capítulos; también puede reportar el heartbeat de pull-stream o reproducción del cliente al mismo tiempo. Antes de llamar, confirme lo siguiente:
  • Autenticación: La clave de API principal no es obligatoria; pueden invocarla tanto la clave principal como una temporal. Para saber cómo obtenerlas, consulte Obtener credenciales de autenticación.
  • Requisitos previos: Consulte con el encryptedTravelId devuelto por Ingresar a Travel.
  • Solicitante: Puede invocarlo su servidor o su cliente. Se recomienda sondear cada 2–5 segundos.

Solicitud HTTP

  • Singapore
  • EE. UU. (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/statusReemplace {WorkspaceId} con su ID de espacio de trabajo real.

Parámetros de solicitud

  • Consultar estado de Travel
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/status?encryptedTravelId={encryptedTravelId}&clientStreamStatus=PLAYING&clientStreamStatusTimeMs=1788940800000' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
Authorization string (Requerido)Autenticación mediante clave de API. No se requiere la clave de API principal; pueden invocarla tanto la clave principal como una temporal.
  • Clave de API principal: comienza con sk-, por ejemplo, sk-xxx.
  • Clave de API temporal: comienza con st-, por ejemplo, st-xxx.
Parámetros de consulta
encryptedTravelId string (Obligatorio)El ID de Travel cifrado de Directing. Devuelto por Enter Travel.
clientStreamStatus string (Opcional)El estado de recepción de flujo o reproducción RTC del cliente, sin distinción entre mayúsculas y minúsculas. Los valores no reconocidos se ignoran. Valores permitidos:
  • DISCONNECTED: no conectado o ha abandonado el canal
  • CONNECTING: conectando al canal RTC
  • CONNECTED: unido, pero la reproducción no ha comenzado o el primer fotograma no ha llegado
  • PLAYING: se ha recibido la transmisión remota y se está renderizando
  • BUFFERING: almacenando en búfer
  • PAUSED: el cliente pausó la reproducción; esto no equivale a pause en el servidor
  • RECONNECTING: reconectando
clientStreamStatusTimeMs long (Opcional)La marca de tiempo en milisegundos del cambio de estado del cliente. Se utiliza junto con clientStreamStatus.

Parámetros de respuesta

  • Travel en ejecución
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-06-04T00:02:00Z",
        "userInstructions": [
            {
                "instruction": "A giant robotic dinosaur suddenly appears",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "Chapter 1",
                "brief": "The detective enters the cyberpunk city",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}
code integerCódigo de retorno. 0 indica éxito; un valor distinto de cero es un código de error.
message stringMensaje de error. null en caso de éxito.
data objectDatos de respuesta. null en caso de fallo.

Propiedades

encryptedTravelId stringID de viaje cifrado.status stringEstado del ciclo de vida del Travel:
  • init: inicializando recursos de sesión
  • pending: en cola o esperando recursos del servicio
  • running: en ejecución; puede llamar a los endpoints de control admitidos según el submodo de creación
  • paused: pausa en el servidor completada; se puede reanudar o rebobinar
  • failed: el Travel falló
  • completed: el Travel ha finalizado; se pueden consultar los artefactos
rtcStatus stringEstado de transmisión RTC del lado del servidor; diferente del clientStreamStatus reportado por el cliente.updateTime stringÚltima hora de actualización, en formato ISO 8601.userInstructions arrayLa lista de instrucciones de texto; null cuando no hay datos. Cada elemento contiene instruction, relativeStartTimeMs / relativeEndTimeMs (milisegundos relativos), startTime / endTime (segundos de línea de tiempo) y status.chapters arrayLa lista de capítulos; null cuando la detección de capítulos aún no se ha activado. Cada elemento contiene chapterId, title, brief, actRange, startTime, endTime y chapterImage.characterActions arrayFijo como una matriz vacía para el modelo Directing.environmentActions arrayFijo como una matriz vacía para el modelo Directing.

Estados previos y notas de llamada

  • Sondee cada 2–5 segundos.
  • En el estado running, puede llamar a los endpoints de control admitidos según creationModel: el modo estándar admite instruct, pause, resume, rewind y end; el modo script admite update-script, pause, resume, rewind y end.
  • Este endpoint no devuelve mode, aspectRatio, playUrl, bgmUrl ni sessionId; la configuración de streaming se basa en la respuesta de Enter Travel.
  • clientStreamStatus es el latido de reproducción del lado del cliente, y rtcStatus es el estado de transmisión del lado del servidor; no son intercambiables.

Códigos de error

Si la llamada al modelo falla y devuelve un error, consulte Códigos de error de HappyOyster para resolverlo.

Siguientes pasos

Cuando el Travel está en running o paused: