Skip to main content

Referencia de API de HappyOyster-Acting-Query Travel Artifacts

Consulta el original grabado y las tres variantes compuestas de un Travel de Acting completado. Para entrega externa, se recomienda withInstructionAndWatermark.

Ámbito

Consulta el original grabado y las tres variantes compuestas de un Travel de Acting completado. withInstruction es la variante con superposición de las instrucciones de proceso del usuario; para entrega externa, se recomienda withInstructionAndWatermark. Antes de realizar la llamada, confirme lo siguiente:
  • Autenticación: Solo se admite la API Key principal; no se pueden utilizar API Keys temporales (código de error 403003).
  • Requisitos previos: El estado del Travel es completed. Una URL original disponible es la condición previa para devolver una respuesta de artefactos. Confírmelo mediante Consultar estado del Travel.
  • Caller: Llamado por su servidor.

Solicitud HTTP

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

Parámetros de solicitud

  • Consultar artefactos del Travel
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 (Requerido)Autenticación mediante API Key. Solo se admite la API Key principal; comienza con sk-, p. ej., sk-xxx. Normalmente se configura como la variable de entorno $DASHSCOPE_API_KEY. Una API Key temporal (que comienza con st-) devuelve 403003.
Parámetros de consulta
encryptedTravelId string (Obligatorio)Un ID de Travel cifrado de Acting con estado completed. Devuelto por Ingresar a Travel.

Parámetros de respuesta

  • Los cuatro artefactos están listos
  • Composición aún en proceso
{
    "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 é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.composeStatus stringEl estado agregado de las tres variantes compuestas:
  • ready: withWatermark, withInstruction y withInstructionAndWatermark están todos en ready
  • partial: al menos una variante compuesta está en ready, pero no todas
  • processing: none de las tres variantes compuestas está en ready
Agrega únicamente las tres variantes compuestas y no incluye original.video objectLas cuatro variantes fijas del video principal. Cada elemento contiene url, status, resolution y durationSec.
  • original: el original grabado; se devuelve preferentemente una representación de 720p cuando está disponible
  • withWatermark: variante compuesta solo con marca de agua
  • withInstruction: variante compuesta con la superposición de instrucciones de proceso del usuario
  • withInstructionAndWatermark: variante compuesta con superposición de instrucciones de proceso del usuario + marca de agua, recomendada para entrega externa
video.*.url stringURL de descarga; null cuando está en processing o unavailable.video.*.status stringEstado por elemento:
  • ready: listo, url es accesible
  • processing: aún componiendo, url=null
  • unavailable: la composición falló o la URL no está disponible temporalmente, url=null
video.*.resolution string"720p" cuando original coincide con 720p; de lo contrario, puede ser null.video.*.durationSec integerLa duración del video analizada uniformemente en segundos; cuando es analizable, todas las variantes ready incluyen este valor. Puede ser null cuando está en processing / unavailable o cuando la duración aún no se puede analizar.

Estados previos y notas de llamada

  • El cliente puede sondear a un intervalo controlado mientras composeStatus != ready.
  • video.withInstruction es la variante con superposición de instrucciones de proceso, no el original sin instrucciones.
  • Para entrega externa, lea video.withInstructionAndWatermark; si su caso de uso solo necesita el original, continúe leyendo video.original.url.
  • Las cuatro variantes de video comparten el mismo resultado de análisis de duración, por lo que dentro de una misma respuesta las variantes listas con una duración analizable devuelven un valor consistente de durationSec.
  • Un Travel finalizado por TRAVEL_NO_STREAM_AUTO_END tiene estado failed y no genera artefactos consultables.
  • No interprete siempre 404000 como "aún no completado": primero lea status y errorCode mediante Consultar estado del Travel o Consultar lista de Travels; para un Travel con estado failed, muestre el motivo del fallo.
Escenarios 404000
EscenarioComportamiento del endpoint
El Travel aún está en progreso (init / pending / running / paused)Devuelve el código de negocio 404000, con message = Video is still being generated, please try again once the process is complete
El Travel está failedDevuelve el código de negocio 404000, con message = Experience failed and no video was produced (errorCode=<errorCode>): <errorMessage>; el fallo es terminal y no se producirá ningún video
El Travel no existe, no le pertenece o no es de tipo ActingDevuelve el código de negocio 404000
La URL original no está disponibleDevuelve el código de negocio 404000; el original es el requisito estricto para todo el endpoint
El original está listo y la composición aún está en procesoHTTP 200; el elemento compuesto correspondiente tiene status=processing, url=null
La composición falló o la URL no está disponible temporalmenteHTTP 200; el elemento compuesto correspondiente tiene status=unavailable, url=null

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