Skip to main content
Mais

API de gerenciamento de tarefas assíncronas

Alguns modelos do Model Studio (como os de geração de imagem e vídeo) usam invocação assíncrona devido ao longo tempo de processamento. O fluxo de trabalho típico consiste em crie uma tarefa para obter um id e, em seguida, consultar o resultado com esse id. O Model Studio oferece APIs de tarefas de uso geral para consultar resultados individuais, verificar o status de múltiplas tarefas em lote e cancele tarefas na fila.

Pré-requisitos

Você pode chamar as APIs de tarefas assíncronas via HTTP. Antes de chamar as APIs, obtenha e configure uma chave de API e, em seguida, defina a chave de API como variável de ambiente.

Consultar o resultado de uma tarefa assíncrona

Descrição da API: Consulta o status e o resultado de uma tarefa com base no task_id. Limite de taxa: 20 QPS por conta Alibaba Cloud (inclui todos os usuários RAM).
  • É possível consultar todas as tarefas da conta Alibaba Cloud proprietária da chave de API atual, incluindo aquelas enviadas com qualquer chave de API dessa conta. Não é possível consultar tarefas de outras contas.
  • Tarefas concluídas ficam retidas por 24 horas (consulte a referência da API da tarefa específica para o período exato). Após a expiração, o sistema exclui automaticamente os dados da tarefa.

Endpoint da requisição 

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

Parâmetros da requisição

Passagem de parâmetros

Campo

Tipo

Obrigatório

Descrição

Exemplo

Header

Authorization

String

Sim

Chave de API no formato Bearer sk-xxx

Bearer sk-xxx

Path

task_id

String

Sim

id da tarefa a consultar.

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Parâmetros de resposta

Campo

Tipo

Descrição

Exemplo

request_id

String

id exclusivo desta requisição.

7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51

output

Object

  • Se a tarefa for bem-sucedida, output contém o objeto de resultado gerado pelo modelo. O conteúdo varia conforme o tipo de tarefa.

  • Em caso de falha total ou parcial da tarefa, output retorna os campos code e message, que explicam o motivo da falha.

  • Para tarefas com múltiplas subtarefas, output pode conter tanto os resultados das subtarefas bem-sucedidas quanto as mensagens de erro das que falharam.

-

output.task_id

String

id da tarefa consultada.

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

output.task_status

String

Status da tarefa.

  • Em tarefas com múltiplas subtarefas, a tarefa principal é considerada bem-sucedida se pelo menos uma subtarefa for concluída com êxito.

  • Subtarefas com falha apresentam erros específicos na saída.

Status da tarefa:

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • UNKNOWN

output.submit_time

String

Horário de envio da tarefa.

2023-12-20 21:36:31.896

output.scheduled_time

String

Horário em que a tarefa foi agendada (momento de início da execução).

2023-12-20 21:36:39.009

output.end_time

String

Horário de término da tarefa.

2023-12-20 21:36:45.913

output.code

String

Código de erro (retornado apenas quando a tarefa falha).

-

output.message

String

Mensagem de erro (retornada apenas quando a tarefa falha).

-

output.task_metrics

Object

Métricas da tarefa, incluindo estatísticas de status das subtarefas.

{

"TOTAL": 4, // Total number of subtasks

"SUCCEEDED": 3, // Number of successful subtasks

"FAILED": 1 // Number of failed subtasks

}

usage

Object

Informações de faturamento desta requisição (varia conforme a tarefa).

"usage": {"image_count": 1}

Exemplo de requisição 

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Caso $DASHSCOPE_API_KEY não esteja definida como variável de ambiente, substitua-a pela sua chave de API real (formato: Bearer sk-xxx).

Exemplo de resposta 

{
    "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 o status de múltiplas tarefas assíncronas

Descrição da API: Consulte múltiplas tarefas assíncronas usando diversos critérios. Verifique o status de várias tarefas em uma única requisição. Limite de taxa: 20 QPS por conta Alibaba Cloud (inclui todos os usuários RAM).
  • É possível consultar todas as tarefas da conta Alibaba Cloud proprietária da chave de API atual, incluindo aquelas enviadas com qualquer chave de API dessa conta. Não é possível consultar tarefas de outras contas.
  • Após o término do período de retenção, o sistema exclui a tarefa e seus dados tornam-se indisponíveis para consulta.

Endpoint da requisição 

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

Parâmetros da requisição

Passagem de parâmetros

Campo

Tipo

Obrigatório

Descrição

Exemplo

Header

Authorization

String

Sim

Chave de API no formato Bearer sk-xxx.

Bearer sk-xxx

Params

task_id

String

Não

id da tarefa a consultar. Especifique um task_id para retornar apenas o status dessa tarefa ou omita-o para consultar múltiplas tarefas.

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

start_time

String

Não

Horário inicial da consulta no formato YYYYMMDDhhmmss. O padrão é 24 horas antes de end_time (se end_time for especificado) ou as últimas 24 horas (se nenhum horário for especificado). Intervalo máximo: 24 horas.

20230420193058 representa 19:30:58 em 20 de abril de 2023.

end_time

String

Não

Horário final da consulta no formato YYYYMMDDhhmmss. O padrão é 24 horas após start_time (se start_time for especificado). Intervalo máximo: 24 horas.

model_name

String

Não

Nome do modelo.

wanx-v1

status

String

Não

Status da tarefa:

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN

page_no

Integer

Não

Número da página de resultados a retornar. Padrão: 1.

-

page_size

Integer

Não

Número de entradas por página. Padrão: 10.

-

Parâmetros de resposta

CampoTipoDescriçãoExemplo
request_idStringid exclusivo desta requisição.7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
dataArrayLista de resultados da 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_idStringid da chave de API.
data[].caller_parent_idStringid da conta Alibaba Cloud.
data[].caller_uidStringid da conta Alibaba Cloud.
data[].gmt_createLongHorário de criação da tarefa (milissegundos desde a época Unix).
data[].start_timeLongHorário de início da tarefa, em milissegundos desde a época Unix.
data[].end_timeLongHorário de término da tarefa, em milissegundos desde a época Unix.
data[].regionStringRegião. Exemplo: cn-hangzhou
data[].request_idStringid da requisição de envio da tarefa.
data[].statusStringStatus da tarefa:
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN
data[].task_idStringid da tarefa.
data[].user_api_unique_keyStringChave de API exclusiva gerada a partir dos parâmetros de API do modelo no momento do envio da tarefa.
data[].model_nameStringNome do modelo.
page_noIntegerNúmero da página atual."page_no": 1
page_sizeIntegerNúmero de entradas por página."page_size": 10
total_pageIntegerNúmero total de páginas."total_page": 4
totalIntegerNúmero total de entradas."total": 39
codeStringCódigo de erro retornado quando a chamada falha."code": "Throttling.RateQuota"
messageStringMensagem de erro retornada quando a chamada falha."message": "Requests rate limit exceeded, please try again later."

Exemplo de requisição 

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

Exemplo de resposta 

{
    "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
}

Cancele uma tarefa assíncrona

Descrição da API: Cancela uma tarefa assíncrona. Apenas tarefas no estado PENDING (na fila, não iniciadas) podem ser canceladas. Limite de taxa: 20 QPS por conta Alibaba Cloud (inclui todos os usuários RAM).
  • É possível cancelar qualquer tarefa da conta Alibaba Cloud proprietária da chave de API atual, incluindo aquelas enviadas com qualquer chave de API dessa conta. Não é possível cancelar tarefas de outras contas.

Endpoint da requisição 

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

Parâmetros da requisição

Passagem de parâmetros

Campo

Tipo

Obrigatório

Descrição

Exemplo

Header

Authorization

String

Sim

Chave de API no formato Bearer sk-xxx.

Bearer sk-xxx

Path

task_id

String

Sim

id da tarefa a cancelar.

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Parâmetros de resposta

Uma requisição de cancelamento bem-sucedida retorna o id da requisição como uma string JSON simples no corpo da resposta. Não há campos de objeto JSON na resposta de sucesso. Para respostas de erro, os seguintes campos são retornados:

Campo

Tipo

Descrição

Exemplo

code

String

Código de erro retornado quando a chamada falha.

"code": "Throttling.RateQuota"

message

String

Mensagem de erro retornada quando a chamada falha.

"message": "Requests rate limit exceeded, please try again later."

Exemplo de requisição 

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

Exemplo de resposta 

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

Códigos de erro

Código de status HTTP

Código de erro

Mensagem de erro

Descrição

400

UnsupportedOperation

Failed to cancel the task. Confirme that the task is in PENDING status.

Falha ao cancelar a tarefa. Apenas tarefas no estado PENDING podem ser canceladas.

Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais