Skip to main content

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

Consultar o ciclo de vida da Viagem Adventure, o status de streaming no lado do servidor e o conjunto de ações do mundo atual; você também pode relatar o heartbeat de pull-stream ou reprodução do cliente ao mesmo tempo.

Escopo

Consultar o ciclo de vida da Viagem Adventure, o status de streaming no lado do servidor e o conjunto de ações do mundo atual; 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
  • China (Pequim)
  • EUA (Virgínia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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-adventure/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 criptografado da Viagem Adventure. 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 significa que a Viagem Adventure suporte pausa no 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": null,
        "chapters": null,
        "characterActions": [
            "dash",
            "jump",
            "crouch",
            "attack"
        ],
        "environmentActions": [
            "ride_motorcycle",
            "enter_exit_car"
        ]
    }
}
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 controlá-la em tempo real via SDK sendCommand
  • failed: a Travel falhou
  • completed: a Viagem terminou; os artefatos podem ser consultados
As capacidades do produto Adventure não possuem estado paused; não crie uma máquina de estados baseada em pausar / retomar.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 null | arrayO Adventure não suporta HTTP instruct, e as ações de exploração não são refletidas neste campo; geralmente null ou [], e pode ser ignorado.chapters arrayA lista de capítulos; null quando nenhum dado de capítulo foi gerado.characterActions arrayIDs de ação disponíveis para o personagem / sujeito atual; [] quando não há recomendação. Geralmente 2–4 são retornados. Ações comuns:
  • dash: correr para frente
  • jump: pular
  • crouch: agachar / deitar
  • attack: atacar
environmentActions arrayIDs de ação de interação com o ambiente disponíveis para a cena atual; [] quando não há recomendação. O servidor seleciona 0–3 de um conjunto fixo de ações por cena e pode retornar um array vazio. Ações comuns:
  • ride_horse: cavalgar
  • ride_bicycle: andar de bicicleta
  • ride_motorcycle: pilotar uma motocicleta
  • enter_exit_car: entrar / sair de um carro
  • open_close_door: abrir / fechar uma porta
  • take_cover: buscar cobertura
  • car_light: acender as luzes do carro; pode aparecer apenas quando enter_exit_car também for retornado
  • car_horn: buzinar; pode aparecer apenas quando enter_exit_car também for retornado

Estados pré-requisitos e notas de chamada

  • Sondar a cada 2–5 segundos.
  • As capacidades do produto Adventure não possuem estado paused; não crie uma máquina de estados baseada em pausar / retomar.
  • characterActions e environmentActions são dicas de ações disponíveis; o controle real ainda é enviado via SDK sendCommand.
  • Este endpoint não retorna mode, 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.
  • O Adventure não suporta HTTP instruct, pause, resume, rewind ou update-script; não integre os seguintes caminhos como capacidades HTTP disponíveis: /travels/instruct, /travels/pause, /travels/resume, /travels/rewind, /travels/update-script.

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

Após a Viagem tornar-se running:
  • O cliente envia controles de direção, ponto de vista e ação via SDK sendCommand (você pode primeiro ler o conjunto de ações retornado por este endpoint).
  • Encerrar Travel: encerre a sessão e processe os artefatos.