Instantánea de video - OpenSearch - Centro de documentación de Alibaba Cloud

La plataforma abierta AI Search permite invocar el servicio de instantáneas de video mediante una API. Este servicio extrae fotogramas clave de los videos y los combina con servicios de OCR, análisis de imágenes o embedding multimodal para habilitar un análisis profundo y un procesamiento estructurado del contenido de video.

Servicios

Nombre del servicio	ID del servicio	Descripción del servicio	Límite de QPS de llamadas a la API (incluye cuenta raíz y usuarios de RAM)
Video Snapshot Service 001	ops-video-snapshot-001	El servicio Video Snapshot Service 001 (ops-video-snapshot-001) extrae contenido de videos mediante la captura de fotogramas clave. Al combinarse con capacidades de embedding multimodal o análisis de imágenes, habilita la recuperación entre modalidades.	5 Nota Para solicitar un límite de QPS de API mayor, envíe un ticket al soporte técnico.

Obtención de credenciales de autenticación

La plataforma abierta AI Search requiere una clave de API para la autenticación. Para obtener instrucciones, consulte Get an API key.
Obtención del endpoint del servicio

Puede invocar el servicio a través de la red pública o de una VPC. Para más detalles, consulte Get the service endpoint.

Creación de una tarea asíncrona

Método de solicitud: POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/async

host: El endpoint del servicio. Puede invocar la API a través de Internet o mediante una VPC. Para más detalles, consulte Get Service Endpoint.

En la consola, haga clic en API Keys en el panel de navegación izquierdo. En Endpoints, verá el Public API Domain (compatible con HTTPS) y el Private API Domain (para entornos VPC). Utilice el menú desplegable de workspace en la esquina superior izquierda para cambiar a su workspace objetivo.

workspace_name: El nombre del workspace, por ejemplo, default.
service_id: El ID del servicio integrado, por ejemplo, ops-video-snapshot-001.

Parámetros de solicitud

Parámetros de encabezado

Autenticación mediante clave de API

Parámetro	Tipo	Obligatorio	Descripción	Valor de ejemplo
Content-Type	String	Sí	Tipo de solicitud: application/json	application/json
Authorization	String	Sí	Clave de API	Bearer OS-d1**2a

Parámetros del cuerpo

Parámetro	Tipo	Obligatorio	Descripción
input	Object(input)	Sí	Especifica el archivo multimedia que se va a procesar.
parameters	Object	No	Especifica los parámetros del servicio.
output	Object(output)	Sí	Controla el formato de salida y la ruta de almacenamiento del archivo.

input

Parámetro	Tipo	Obligatorio	Descripción
content	String	No	Datos de video codificados en Base64. Compatible con mp4, avi, mkv, mov, flv y webm. Nota Los parámetros input.content e input.oss son mutuamente excluyentes. Especifique solo uno. Uso de datos Base64: Pase la cadena Base64 codificada al parámetro `content` con el formato `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, donde: `video/<FORMAT>`: El formato de video. Por ejemplo, para un video MP4, utilice `video/mp4`. `<BASE64_VIDEO>`: Los datos de video codificados en Base64. Ejemplo: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	No	La ruta de OSS del archivo de entrada, por ejemplo, oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	No	El nombre del archivo de video. Si no se especifica, el nombre se analiza a partir del contenido del archivo.

Parameters

Parámetro	Tipo	Obligatorio	Descripción
interval	Int	No	Intervalo de extracción de fotogramas en segundos. El valor predeterminado es 1 segundo.
format	String	No	Formato del fotograma de salida. Compatible con jpg y png. El valor predeterminado es jpg.

output

Parámetro

Tipo

Obligatorio

Descripción

type

String

base64: Devuelve el contenido de la imagen en formato Base64. Solo compatible con llamadas síncronas.

oss: Almacena los fotogramas extraídos en OSS (predeterminado).

oss

String

La ruta de OSS para los archivos de salida. Obligatorio cuando type es oss.

Ejemplo: oss://<BUCKET_NAME>/result/path

Parámetros de respuesta

Parámetro	Tipo	Descripción	Valor de ejemplo
result.task_id	String	El ID único de la tarea de extracción de video.	snapshot-xxxx-abc-123

Ejemplo de solicitud con curl

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Key>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/async"
  --data '{
    "input":{
        "oss" : "oss://<BUCKET_NAME>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<BUCKET_NAME>/result/path"
    }
  }' \

Ejemplo de respuesta

{
  "request_id":"de81e152284a2d3b1f4315d*******",
  "latency":21,
  "usage":{},
  "result":{
        "task_id":"snapshot-20250617102142-110841*******-*******",
        "status":"PENDING"
            }
 }

Consulta del estado de una tarea asíncrona

Método de solicitud: GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/async/task-status?task_id={task_id}

host: El endpoint del servicio. Puede invocar la API a través de Internet o mediante una VPC. Para más detalles, consulte Get Service Endpoint.

workspace_name: El nombre del workspace, por ejemplo, default.
service_id: El ID del servicio integrado, por ejemplo, ops-video-snapshot-001.

Parámetros de solicitud

Nombre del parámetro	Tipo	Obligatorio	Descripción	Ejemplo
service_id	String	Sí	ID del servicio.	ops-video-snapshot-001
task_id	String	Sí	El ID de tarea devuelto al crear la tarea asíncrona de instantáneas de video.	snapshot-xxxx-abc-123

Parámetros de respuesta

Parámetro	Tipo	Descripción	Valor de ejemplo
result.task_id	String	El ID único de la tarea de extracción de video.	snapshot-xxxx-abc-123
result.status	String	Estado de la tarea: PENDING: En espera de procesamiento SUCCESS: Tarea completada correctamente FAIL: La tarea falló y se detuvo	PENDING
result.error	String	Mensaje de error cuando el estado es FAIL. Vacío en condiciones normales.
result.data	List(SnapshotResult)	Resultados del procesamiento de video.
usage.image_count	Int	Número de fotogramas extraídos.

SnapshotResult

Parámetro	Tipo	Descripción
frame_index	Int	Número de fotograma en el video.
path	String	La ruta de OSS del archivo. Cuando output se establece en OSS, este campo muestra la ruta de almacenamiento codificada en URL del fotograma extraído en OSS.
content	String	Contenido de imagen codificado en Base64. Solo está presente content o path, y este campo aparece únicamente en tareas síncronas.
frame_time	Float	Marca temporal del fotograma extraído en el video, en segundos.

Ejemplo de solicitud con curl

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Your API Key>" \
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/async/task-status?task_id=snapshot-20250617102142-1108418170738252-******" \

Ejemplo de respuesta

{
  "request_id":"83b423e2e63613a878c369c20******",
  "latency":11,
  "usage":{
      "image":64
          },
  "result":{
      "task_id":"snapshot-20250617102142-1108418170738252-******",
      "status":"SUCCESS",
       "data":[
                {
                  "frame_index": 0,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_0.jpg",
                  "frame_time": 0.0
                },
                ......
                {
                  "frame_index": 1890,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_63.jpg",
                  "frame_time": 63.0
                }                
              ]
            }
}

Creación de una tarea síncrona de instantáneas de video

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/sync

host: El endpoint del servicio. Puede invocar la API a través de Internet o mediante una VPC. Para más detalles, consulte Get Service Endpoint.

workspace_name: El nombre del workspace, por ejemplo, default.
service_id: El ID del servicio integrado, por ejemplo, ops-video-snapshot-001.

Parámetros de solicitud

Parámetros de encabezado

Autenticación mediante clave de API

Parámetro	Tipo	Obligatorio	Descripción	Valor de ejemplo
Content-Type	String	Sí	Tipo de solicitud: application/json	application/json
Authorization	String	Sí	Clave de API	Bearer OS-d1**2a

Parámetros del cuerpo

Parámetro	Tipo	Obligatorio	Descripción
input	Object(input)	Sí	Especifica el archivo multimedia que se va a procesar.
parameters	Object	No	Especifica los parámetros del servicio.
output	Object(output)	Sí	Controla el formato de salida y la ruta de almacenamiento del archivo.

input

Parámetro	Tipo	Obligatorio	Descripción
content	String	No	Datos de video codificados en Base64. Compatible con mp4, avi, mkv, mov, flv y webm. Nota Los parámetros input.content e input.oss son mutuamente excluyentes. Especifique solo uno. Uso de datos Base64: Pase la cadena Base64 codificada al parámetro `content` con el formato `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, donde: `video/<FORMAT>`: El formato de video. Por ejemplo, para un video MP4, utilice `video/mp4`. `<BASE64_VIDEO>`: Los datos de video codificados en Base64. Ejemplo: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	No	La ruta de OSS del archivo de entrada, por ejemplo, oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	No	El nombre del archivo de video. Si no se especifica, el nombre se analiza a partir del contenido del archivo.

Parameters

Parámetro	Tipo	Obligatorio	Descripción
interval	Int	No	Intervalo de extracción de fotogramas en segundos. El valor predeterminado es 1 segundo.
format	String	No	Formato del fotograma de salida. Compatible con jpg y png. El valor predeterminado es jpg.

output

Parámetro

Tipo

Obligatorio

Descripción

type

String

base64: Devuelve el contenido de la imagen en formato Base64. Solo compatible con llamadas síncronas.

oss: Almacena los fotogramas extraídos en OSS (predeterminado).

oss

String

La ruta de OSS para los archivos de salida. Obligatorio cuando type es oss.

Ejemplo: oss://<BUCKET_NAME>/result/path

Parámetros de respuesta

Parámetro	Tipo	Descripción	Valor de ejemplo
result.task_id	String	El ID único de la tarea de extracción de video.	snapshot-xxxx-abc-123

Ejemplo de solicitud con curl

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Key>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/sync"
  --data '{
    "input":{
        "oss" : "oss://<BUCKET_NAME>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<BUCKET_NAME>/result/path"
    }
  }' \

Ejemplo de respuesta

{
  "request_id":"83b423e2e63613a878c369c20******",
  "latency":11,
  "usage":{
      "image":64
          },
  "result":{
      "task_id":"snapshot-20250617102142-1108418170738252-b******",
      "status":"SUCCESS",
       "data":[
                {
                  "frame_index": 0,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_0.jpg",
                  "frame_time": 0.0
                },
                ......
                {
                  "frame_index": 1890,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_63.jpg",
                  "frame_time": 63.0
                }                
              ]
            }
}

Referencia de códigos de estado

Si una solicitud falla, la respuesta incluye un código y un mensaje que explican el error.

{
    "request_id": "6F33AFB6-A35C-4DA7-AFD2-9EA16CCF****",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\""
}

Código de estado HTTP	Código de error	Descripción
200	-	La solicitud se realizó correctamente. Esto incluye casos en los que la tarea misma falló. Compruebe result.status para conocer el estado real de la tarea.
404	BadRequest.TaskNotExist	La tarea no existe.
400	InvalidParameter	Solicitud no válida.
500	InternalServerError	Error interno.

Para obtener más información sobre los códigos de estado, consulte Status Code Reference.