Skip to main content

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

Consulta o original gravado e as três variantes compostas de uma Viagem de Acting concluída. Para entrega externa, recomenda-se withInstructionAndWatermark.

Escopo

Consulta o original gravado e as três variantes compostas de uma Viagem de Acting concluída. withInstruction é a variante de sobreposição das instruções de processo do usuário; para entrega externa, recomenda-se withInstructionAndWatermark. Antes de chamar, confirme o seguinte:
  • Autenticação: Apenas a API Key primária é suportada; API Keys temporárias não podem ser usadas (código de erro 403003).
  • Pré-requisitos: O status da Viagem é completed. Uma URL original disponível é a pré-condição para retornar uma resposta de artefatos. Confirme via Consultar Status da Viagem.
  • Caller: Chamado pelo seu servidor.

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/artifactsSubstitua {WorkspaceId} pelo seu ID do Workspace real.

Parâmetros da solicitação

  • Consultar artefatos da Viagem
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/artifacts?encryptedTravelId={encryptedTravelId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
Authorization string (Obrigatório)Autenticação por API Key. Apenas a API Key primária é suportada; ela começa com sk-, ex. sk-xxx. É tipicamente configurada como a variável de ambiente $DASHSCOPE_API_KEY. Uma API Key temporária (começando com st-) retorna 403003.
Parâmetros de consulta
encryptedTravelId string (Obrigatório)Um ID de Viagem criptografado do Acting com status completed. Retornado por Entrar na Viagem.

Parâmetros de resposta

  • Todos os quatro artefatos prontos
  • Composição ainda em processamento
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "composeStatus": "ready",
        "video": {
            "original": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_raw.mp4?v=2",
                "status": "ready",
                "resolution": "720p",
                "durationSec": 180
            },
            "withWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_wm.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstruction": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_overlay.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstructionAndWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_all.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            }
        }
    }
}
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.composeStatus stringO status agregado das três variantes compostas:
  • ready: withWatermark, withInstruction e withInstructionAndWatermark estão todos ready
  • partial: pelo menos uma variante composta está ready, mas não todas
  • processing: none das três variantes compostas está ready
Ele agrega apenas as três variantes compostas e não inclui original.video objectAs quatro variantes fixas do vídeo principal. Cada item contém url, status, resolution e durationSec.
  • original: o original gravado; uma representação de 720p é retornada preferencialmente quando disponível
  • withWatermark: variante composta apenas com marca d'água
  • withInstruction: variante composta com a sobreposição de instrução de processo do usuário
  • withInstructionAndWatermark: variante composta de sobreposição de instrução de processo do usuário + marca d'água, recomendada para entrega externa
video.*.url stringURL de download; null quando processing ou unavailable.video.*.status stringStatus por item:
  • ready: pronto, url está acessível
  • processing: ainda compondo, url=null
  • unavailable: falha na composição ou URL temporariamente indisponível, url=null
video.*.resolution string"720p" quando original corresponde a 720p; caso contrário, pode ser null.video.*.durationSec integerA duração do vídeo uniformemente analisada em segundos; quando analisável, todas as variantes ready carregam este valor. Pode ser null quando processing / unavailable ou quando a duração ainda não pode ser analisada.

Estados pré-requisitos e notas de chamada

  • O cliente pode consultar em um intervalo controlado enquanto composeStatus != ready.
  • video.withInstruction é a variante de sobreposição de instrução de processo, não o original sem instrução.
  • Para entrega externa, leia video.withInstructionAndWatermark; se o seu negócio precisar apenas do original, continue lendo video.original.url.
  • As quatro variantes de vídeo compartilham o mesmo resultado de análise de duração, portanto, dentro de uma única resposta, as variantes prontas com duração analisável retornam um durationSec consistente.
  • Um Travel encerrado por TRAVEL_NO_STREAM_AUTO_END é failed e não gera artefatos consultáveis.
  • Não renderize sempre 404000 como "ainda não concluído": primeiro leia status e errorCode via Consultar Status da Viagem ou Consultar Lista de Viagens; para uma Viagem failed, mostre o motivo da falha.
Cenários 404000
CenárioComportamento do endpoint
A Viagem ainda está em andamento (init / pending / running / paused)Retorna o código de negócio 404000, com message = Video is still being generated, please try again once the process is complete
A Viagem está failedRetorna o código de negócio 404000, com message = Experience failed and no video was produced (errorCode=<errorCode>): <errorMessage>; a falha é terminal e nenhum vídeo será produzido
A Viagem não existe, não pertence a você ou não é do tipo ActingRetorna o código de negócio 404000
A URL original está indisponívelRetorna o código de negócio 404000; o original é o bloqueio rígido para todo o endpoint
O original está pronto e a composição ainda está em processamentoHTTP 200; o item composto correspondente tem status=processing, url=null
A composição falhou ou a URL está temporariamente indisponívelHTTP 200; o item composto correspondente tem status=unavailable, url=null

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