¿Cómo consultar y cancelar tareas asíncronas? - Alibaba Cloud Model Studio

Algunos modelos de Model Studio (como los de generación de imágenes y videos) utilizan invocación asíncrona debido a sus largos tiempos de procesamiento. El flujo de trabajo típico consiste en crear una tarea para obtener un ID y luego consultar el resultado usando ese ID. Model Studio proporciona APIs de tareas de propósito general para consultar resultados individuales, verificar el estado de múltiples tareas en lote y cancelar tareas en cola.

Requisitos previos

Puede llamar a las API de tareas asíncronas mediante HTTP.

Antes de llamar a las API, obtenga y configure una clave API, y luego configure la clave API como variable de entorno.

Consultar el resultado de una tarea asíncrona

Descripción de la API: Consulta el estado y el resultado de una tarea basándose en su task_id.

Límite de tasa: 20 QPS por cuenta de Alibaba Cloud (incluye todos los usuarios RAM).

Importante

Puede consultar todas las tareas bajo la cuenta de Alibaba Cloud propietaria de la clave API actual, incluidas las tareas enviadas con cualquier clave API bajo dicha cuenta. No puede consultar tareas de otras cuentas.
Las tareas completadas se conservan durante 24 horas (consulte la referencia de la API de la tarea específica para conocer el periodo exacto). Tras la expiración, el sistema elimina automáticamente los datos de la tarea.

Endpoint de solicitud

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Parámetros de solicitud

Parameter passing	Campo	Tipo	Obligatorio	Descripción	Ejemplo
Header	Authorization	String	Sí	Clave API en formato `Bearer sk-xxx`	Bearer sk-xxx
Ruta	task_id	String	Sí	El ID de la tarea a consultar.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Parámetros de respuesta

Campo	Tipo	Descripción	Ejemplo
request_id	String	El ID único para esta solicitud.	7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
output	Object	Si la tarea tiene éxito, `output` contiene el objeto de resultado generado por el modelo. El contenido varía según el tipo de tarea. Si la tarea falla o falla parcialmente, `output` devuelve los campos `code` y `message` que explican el motivo del fallo. Para tareas con múltiples subtareas, `output` puede contener tanto los resultados de las subtareas exitosas como los mensajes de error de las fallidas.	-
output.task_id	String	El ID de la tarea consultada.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1
output.task_status	String	El estado de la tarea. Para tareas con múltiples subtareas, la tarea principal se considera exitosa si al menos una subtarea tiene éxito. Las subtareas fallidas muestran errores específicos en la salida.	Estado de la tarea: PENDING RUNNING SUCCEEDED FAILED UNKNOWN
output.submit_time	String	La hora en que se envió la tarea.	2023-12-20 21:36:31.896
output.scheduled_time	String	La hora en que se programó la tarea (cuando comenzó a ejecutarse).	2023-12-20 21:36:39.009
output.end_time	String	La hora en que finalizó la tarea.	2023-12-20 21:36:45.913
output.code	String	El código de error (devuelto solo cuando falla la tarea).	-
output.message	String	El mensaje de error (devuelto solo cuando falla la tarea).	-
output.task_metrics	Object	Métricas de la tarea, incluidas estadísticas del estado de las subtareas.	`{` `"TOTAL": 4, // Total number of subtasks` `"SUCCEEDED": 3, // Number of successful subtasks` `"FAILED": 1 // Number of failed subtasks` `}`
usage	Object	La información de facturación para esta solicitud (varía según la tarea).	`"usage": {"image_count": 1}`

Ejemplo de solicitud

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

NotaSi $DASHSCOPE_API_KEY no está configurada como variable de entorno, reemplácela con su clave API real (formato: Bearer sk-xxx).

SDK de Python

La interfaz de tareas asíncronas es independiente del tipo específico de tarea. Los métodos fetch, list y cancel pueden invocarse en cualquier clase de tarea asíncrona (como ImageSynthesis, VideoSynthesis, Transcription, etc.). Todos solicitan /api/v1/tasks y pueden consultar cualquier tarea bajo la cuenta actual.

import os
from dashscope import ImageSynthesis

task_id = '73205176-xxxx-xxxx-xxxx-16bd5d902219'
resp = ImageSynthesis.fetch(
    task_id,
    api_key=os.getenv('DASHSCOPE_API_KEY'),
)
print(resp.output)

CLI de dashscope

Llamada a través de la línea de comandos dashscope.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# Query task status (e.g., video-synthesis)
dashscope video-synthesis fetch <task_id>

NotaActualmente, la CLI de dashscope admite la gestión de tareas fetch/list/cancel únicamente para el subcomando video-synthesis; image-synthesis, transcription y otros subcomandos aún no son compatibles. Para consultar otros tipos de tareas, utilice el SDK de Python o curl como se muestra arriba.

ImportanteEl asistente interactivo SDK Expert puede realizar las mismas tareas de desarrollo y solución de problemas mediante lenguaje natural; consulte

DashScope SDK Expert.

Para la tabla completa de regiones, consulte Resumen de URL base.

Ejemplo de respuesta

{
    "request_id": "45ac7f13-xxxx-xxxx-xxxx-e03c35068d83",
    "output": {
        "task_id": "73205176-xxxx-xxxx-xxxx-16bd5d902219",
        "task_status": "SUCCEEDED",
        "submit_time": "2023-12-20 21:36:31.896",
        "scheduled_time": "2023-12-20 21:36:39.009",
        "end_time": "2023-12-20 21:36:45.913",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx1.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx2.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx3.png"
            },
            {
                "code": "DataInspectionFailed",
                "message": "Output data may contain inappropriate content.",
            }
        ],
        "task_metrics": {
            "TOTAL": 4,
            "SUCCEEDED": 3,
            "FAILED": 1
        }
    },
    "usage": {
        "image_count": 3
    }
}

Consultar el estado de múltiples tareas asíncronas

Descripción de la API: Consulta múltiples tareas asíncronas utilizando diversas condiciones. Verifique el estado de varias tareas en una sola solicitud.

Límite de tasa: 20 QPS por cuenta de Alibaba Cloud (incluye todos los usuarios RAM).

Importante

Puede consultar todas las tareas bajo la cuenta de Alibaba Cloud propietaria de la clave API actual, incluidas las tareas enviadas con cualquier clave API bajo dicha cuenta. No puede consultar tareas de otras cuentas.
Una vez expirado el periodo de retención, el sistema elimina la tarea y sus datos dejan de ser consultables.

Endpoint de solicitud

GET https://dashscope.aliyuncs.com/api/v1/tasks

Parámetros de solicitud

Parameter passing	Campo	Tipo	Obligatorio	Descripción	Ejemplo
Header	Authorization	String	Sí	La clave API, en formato Bearer sk-xxx.	Bearer sk-xxx
Params	task_id	String	No	El ID de la tarea a consultar. Especifique un task_id para devolver únicamente el estado de esa tarea, u omítalo para consultar múltiples tareas.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1
	start_time	String	No	Hora de inicio de la consulta en formato `YYYYMMDDhhmmss`. El valor predeterminado es 24 horas antes de end_time (si se especifica end_time), o las últimas 24 horas (si no se especifica ninguna hora). Rango máximo: 24 horas.	20230420193058 representa las 19:30:58 del 20 de abril de 2023.
	end_time	String	No	Hora de finalización de la consulta en formato `YYYYMMDDhhmmss`. El valor predeterminado es 24 horas después de start_time (si se especifica start_time). Rango máximo: 24 horas.
	model_name	String	No	El nombre del modelo.	wanx-v1
	status	String	No	El estado de la tarea: PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN
	page_no	Integer	No	El número de página de los resultados a devolver. Valor predeterminado: 1.	-
	page_size	Integer	No	El número de entradas por página. Valor predeterminado: 10.	-

Parámetros de respuesta

Campo	Tipo	Descripción	Ejemplo
request_id	String	El ID único para esta solicitud.	7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
data	Array	Una lista de resultados de consulta.	`"data": [ { "api_key_id": "235", "caller_uid": "1808342417264262", "end_time": 1682527200093, "gmt_create": 1682514589152, "model_name": "paraformer-16k-1", "region": "cn-hangzhou", "request_id": "32b67b58-xxxx-xxxx-xxxx-230f0aee64d9", "start_time": 1682515862179, "status": "FAILED", "task_id": "cf52b16b-xxxx-xxxx-xxxx-17f9c211440c", "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-16k-1" } ]`
data[].api_key_id	String	El ID de la clave API.
data[].caller_parent_id	String	El ID de la cuenta de Alibaba Cloud.
data[].caller_uid	String	El ID de la cuenta de Alibaba Cloud.
data[].gmt_create	Long	La hora de creación de la tarea (milisegundos desde la época).
data[].start_time	Long	La hora en que comenzó la tarea, en milisegundos desde la época.
data[].end_time	Long	La hora en que finalizó la tarea, en milisegundos desde la época.
data[].region	String	La región. Ejemplo: cn-hangzhou
data[].request_id	String	El ID de solicitud para el envío de la tarea.
data[].status	String	El estado de la tarea: PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN
data[].task_id	String	El ID de la tarea.
data[].user_api_unique_key	String	Una clave API única generada a partir de los parámetros API del modelo al enviar la tarea.
data[].model_name	String	El nombre del modelo.
page_no	Integer	El número de página actual.	`"page_no": 1`
page_size	Integer	El número de entradas por página.	`"page_size": 10`
total_page	Integer	El número total de páginas.	`"total_page": 4`
total	Integer	El número total de entradas.	`"total": 39`
code	String	El código de error devuelto cuando falla la llamada.	`"code": "Throttling.RateQuota"`
message	String	El mensaje de error devuelto cuando falla la llamada.	`"message": "Requests rate limit exceeded, please try again later."`

Ejemplo de solicitud

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/?start_time=xxx&end_time=xxx&status=xxx' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

SDK de Python

import os
from dashscope import ImageSynthesis

resp = ImageSynthesis.list(
    start_time='20230420193000',
    end_time='20230420203000',
    status='RUNNING',
    page_no=1,
    page_size=10,
    api_key=os.getenv('DASHSCOPE_API_KEY'),
)
print(resp.output)

list también admite filtrado por model_name, api_key_id, region, etc. Los parámetros se corresponden uno a uno con los parámetros de consulta de la API HTTP.

Notafetch, list y cancel son compatibles tanto con dominios específicos del espacio de trabajo ({WorkspaceId}.{region}.maas.aliyuncs.com) como con el dominio general (dashscope.aliyuncs.com), y pueden invocarse entre regiones. La API Key debe coincidir con el espacio de trabajo correspondiente.

CLI de dashscope

Llamada a través de la línea de comandos dashscope.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# List video synthesis tasks (supports --start-time/--end-time/--status/--model-name filters)
dashscope video-synthesis list --status RUNNING -s 10

NotaActualmente, la CLI de dashscope admite la gestión de tareas únicamente para el subcomando video-synthesis; para consultar otros tipos de tareas (imagen, transcripción, etc.), utilice el SDK de Python o curl como se muestra arriba.

ImportanteEl asistente interactivo SDK Expert puede realizar las mismas tareas de desarrollo y solución de problemas mediante lenguaje natural; consulte

DashScope SDK Expert.

Para la tabla completa de regiones, consulte Resumen de URL base.

Ejemplo de respuesta

{
    "total": 2,
    "data": [
        {
            "api_key_id": "15xxxx",
            "caller_parent_id": "xxxxxxxxx",
            "caller_uid": "xxxxxxxxx",
            "gmt_create": 1745568428109,
            "model_name": "wanx2.1-kf2v-plus",
            "region": "cn-beijing",
            "request_id": "1abfc3c8-dd25-98da-ad0b-xxxxxx",
            "start_time": 1745568428138,
            "status": "RUNNING",
            "task_id": "50e2ccea-abc4-43d7-a0dc-xxxxxx",
            "user_api_unique_key": "apikey:v1:aigc:image2video:video-synthesis:wanx2.1-kf2v-plus"
        },
        {
            "api_key_id": "15xxxx",
            "caller_parent_id": "xxxxxxxxx",
            "caller_uid": "xxxxxxxxx",
            "end_time": 1745568302481,
            "gmt_create": 1745568293253,
            "model_name": "wanx2.1-t2i-turbo",
            "region": "cn-beijing",
            "request_id": "f6bf34d9-bf87-9e8b-9ed4-xxxxxx",
            "start_time": 1745568293273,
            "status": "SUCCEEDED",
            "task_id": "3c777dbc-8cc6-4d80-aa90-xxxxxx",
            "user_api_unique_key": "apikey:v1:aigc:text2image:image-synthesis:wanx2.1-t2i-turbo"
        }
    ],
    "total_page": 1,
    "page_no": 1,
    "request_id": "f6756b7e-d0bb-9b74-813a-xxxxxx",
    "page_size": 10
}

Cancelar una tarea asíncrona

Descripción de la API: Cancela una tarea asíncrona. Solo se pueden cancelar las tareas en estado PENDING (en cola, no iniciadas).

Límite de tasa: 20 QPS por cuenta de Alibaba Cloud (incluye todos los usuarios RAM).

Importante

Puede cancelar cualquier tarea bajo la cuenta de Alibaba Cloud propietaria de la clave API actual, incluidas las tareas enviadas con cualquier clave API bajo dicha cuenta. No puede cancelar tareas de otras cuentas.

Endpoint de solicitud

POST https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}/cancel

Parámetros de solicitud

Parameter passing	Campo	Tipo	Obligatorio	Descripción	Ejemplo
Header	Authorization	String	Sí	La clave API, en formato Bearer sk-xxx.	Bearer sk-xxx
Ruta	task_id	String	Sí	El ID de la tarea a cancelar.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Parámetros de respuesta

Una solicitud de cancelación exitosa devuelve el ID de solicitud como una cadena JSON simple en el cuerpo de la respuesta. No hay campos de objeto JSON en la respuesta exitosa.

Para respuestas de error, se devuelven los siguientes campos:

Campo	Tipo	Descripción	Ejemplo
code	String	El código de error devuelto cuando falla la llamada.	`"code": "Throttling.RateQuota"`
message	String	El mensaje de error devuelto cuando falla la llamada.	`"message": "Requests rate limit exceeded, please try again later."`

Ejemplo de solicitud

curl -X POST 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219/cancel' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

SDK de Python

import os
from dashscope import ImageSynthesis

task_id = '73205176-xxxx-xxxx-xxxx-16bd5d902219'
resp = ImageSynthesis.cancel(
    task_id,
    api_key=os.getenv('DASHSCOPE_API_KEY'),
)
print(resp)

Solo se pueden cancelar las tareas con estado PENDING; otros estados devolverán un error.

CLI de dashscope

Llamada a través de la línea de comandos dashscope.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# Cancel task (e.g., video-synthesis, only PENDING status can be canceled)
dashscope video-synthesis cancel <task_id>

NotaActualmente, la CLI de dashscope admite cancel únicamente para el subcomando video-synthesis; para cancelar otros tipos de tareas, utilice el SDK de Python o curl como se muestra arriba.

ImportanteEl asistente interactivo SDK Expert puede realizar las mismas tareas de desarrollo y solución de problemas mediante lenguaje natural; consulte

DashScope SDK Expert.

Para la tabla completa de regiones, consulte Resumen de URL base.

Ejemplo de respuesta

"45ac7f13-xxxx-xxxx-xxxx-e03c35068d83"

Códigos de error

Código de estado HTTP	Código de error	Mensaje de error	Descripción
400	UnsupportedOperation	Error al cancelar la tarea. Confirme que la tarea esté en estado PENDING.	Error en la cancelación de la tarea. Solo se pueden cancelar las tareas en estado `PENDING`.