Skip to main content

Referência da API HappyOyster-Directing-Query Travel Status

Consulte o ciclo de vida da Viagem do Directing, o status de streaming no lado do servidor, as instruções de texto executadas e as informações dos capítulos; você também pode relatar o heartbeat de pull-stream ou reprodução do cliente ao mesmo tempo.

Escopo

Consulte o ciclo de vida da Viagem do Directing, o status de streaming no lado do servidor, as instruções de texto executadas e as informações dos capítulos; você também pode relatar o heartbeat de pull-stream ou reprodução do cliente ao mesmo tempo. Antes de chamar, confirme o seguinte:
  • Autenticação: A Chave de API primária não é obrigatória; tanto a chave primária quanto uma temporária podem chamá-la. Para saber como obtê-las, veja Obter credenciais de autenticação.
  • Pré-requisitos: Consulte com o encryptedTravelId retornado por Entrar na Viagem.
  • Chamador: Tanto seu servidor quanto seu cliente podem fazer a chamada. Recomenda-se consultar a cada 2–5 segundos.

Solicitação HTTP

  • Singapore
  • EUA (Virgínia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/statusSubstitua {WorkspaceId} pelo seu ID do Workspace real.

Parâmetros da solicitação

  • Consultar status da Viagem
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 (Obrigatório)Autenticação por Chave de API. A Chave de API primária não é obrigatória; tanto a chave primária quanto uma temporária podem chamá-lo.
  • API Key Primária: começa com sk-, ex. sk-xxx.
  • Chave de API Temporária: começa com st-, por exemplo, st-xxx.
Parâmetros de consulta
encryptedTravelId string (Obrigatório)O ID de Viagem criptografado do Directing. Retornado por Entrar na Viagem.
clientStreamStatus string (Opcional)O status de recebimento de fluxo RTC ou reprodução do cliente, sem distinção entre maiúsculas e minúsculas. Valores não reconhecidos são ignorados. Valores permitidos:
  • DISCONNECTED: não conectado ou saiu do canal
  • CONNECTING: conectando ao canal RTC
  • CONNECTED: entrou, mas a reprodução não começou ou o primeiro quadro não chegou
  • PLAYING: o fluxo remoto foi recebido e está sendo renderizado
  • BUFFERING: bufferizando
  • PAUSED: o cliente pausou a reprodução; isso não equivale à pause do lado do servidor
  • RECONNECTING: reconectando
clientStreamStatusTimeMs long (Opcional)O timestamp em milissegundos da mudança de estado do cliente. Usado em conjunto com clientStreamStatus.

Parâmetros de resposta

  • Viagem em execução
{
    "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 sucesso; diferente de zero é um código de erro.
message stringMensagem de erro. null em caso de sucesso.
data objectDados da resposta. null em caso de falha.

Propriedades

encryptedTravelId stringTravel ID criptografado.status stringStatus do ciclo de vida da Viagem:
  • init: inicializando recursos da sessão
  • pending: na fila ou aguardando recursos do serviço
  • running: em execução; você pode chamar os endpoints de controle suportados de acordo com o submodo de criação
  • paused: pausa no lado do servidor concluída; pode ser retomada ou retrocedida
  • failed: a Travel falhou
  • completed: a Viagem terminou; os artefatos podem ser consultados
rtcStatus stringStatus de streaming RTC do lado do servidor; diferente do clientStreamStatus relatado pelo cliente.updateTime stringÚltima hora de atualização, no formato ISO 8601.userInstructions arrayA lista de instruções de texto; null quando não há dados. Cada item contém instruction, relativeStartTimeMs / relativeEndTimeMs (milissegundos relativos), startTime / endTime (segundos da linha do tempo) e status.chapters arrayA lista de capítulos; null quando a detecção de capítulos ainda não foi acionada. Cada item contém chapterId, title, brief, actRange, startTime, endTime e chapterImage.characterActions arrayFixo como um array vazio para o modelo Directing.environmentActions arrayFixo como um array vazio para o modelo Directing.

Estados pré-requisitos e notas de chamada

  • Sondar a cada 2–5 segundos.
  • No status running, você pode chamar os endpoints de controle suportados de acordo com creationModel: o modo padrão suporta instruct, pause, resume, rewind e end; o modo de script suporta update-script, pause, resume, rewind e end.
  • Este endpoint não retorna mode, aspectRatio, playUrl, bgmUrl ou sessionId; a configuração de streaming é baseada na resposta de Entrar na viagem.
  • clientStreamStatus é o heartbeat de reprodução do lado do cliente, e rtcStatus é o status de streaming do lado do servidor; eles não são intercambiáveis.

Códigos de erro

Se a chamada do modelo falhar e retornar um erro, consulte Códigos de Erro do HappyOyster para resolvê-lo.

Próximos passos

Quando a Viagem está running ou paused: