Skip to main content

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

Consulta o ciclo de vida da Viagem Acting, o status de streaming no servidor, as instruções de texto enviadas e as informações do capítulo; você também pode reportar o heartbeat de pull-stream ou reprodução do cliente ao mesmo tempo.

Escopo

Consulta o ciclo de vida da Viagem de Acting, o status de streaming do lado do servidor, as instruções de texto enviadas e as informações de capítulos; você também pode relatar o heartbeat de recebimento de fluxo 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-acting/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-acting/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 Acting. 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 o 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
  • Falha na Viagem
{
    "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 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 enviar instruções de texto, pausar ou encerrar
  • paused: pausado no lado do servidor; você pode enviar instruções de texto, retomar ou encerrar
  • failed: a Viagem falhou; veja errorCode / errorMessage para o motivo
  • 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 (texto da instrução), relativeStartTimeMs / relativeEndTimeMs (milissegundos relativos), startTime / endTime (segundos da linha do tempo) e status (status de execução).chapters arrayA lista de capítulos; null quando a detecção de capítulos não foi acionada. Cada item contém chapterId, title, brief, actRange, startTime, endTime e chapterImage.characterActions array<string> | nullActing não suporta controle de ação via SDK; retorna um array vazio; null quando failed.environmentActions array<string> | nullActing não suporta controle de ação de ambiente via SDK; retorna um array vazio; null quando failed.errorCode stringRetornado apenas quando status=failed; um código de motivo de falha estruturado. Veja Códigos de erro para valores.errorMessage stringRetornado junto com errorCode; uma descrição de falha em inglês. Faça a ramificação baseada em errorCode, não em errorMessage.

Estados pré-requisitos e notas de chamada

  • Recomenda-se sondar a cada 2–5 segundos.
  • Tanto running quanto paused permitem chamar Enviar Instrução de Processo; enviar uma instrução no estado paused não retoma automaticamente a Viagem.
  • Este endpoint não retorna mode, aspectRatio, playUrl, bgmUrl ou sessionId; a configuração de streaming e a orientação do player são baseadas 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.
  • Acting não suporta o sendCommand do SDK; não crie controles de direção ou ação baseados nos dois arrays de ação vazios.
  • failed é um estado terminal e nenhum vídeo será produzido; mostre o motivo da falha baseado em errorCode e não exiba como "ainda não concluído".

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: