Integração e uso da API Flux Tasks

A principal funcionalidade da API Flux Tasks é consultar o status de execução de uma tarefa por meio do ID da tarefa da plataforma retornado pela API Flux Images Generation ou API Flux Videos. Este documento apresentará detalhadamente as instruções de integração da API Flux Tasks, ajudando você a integrar facilmente e aproveitar plenamente os poderosos recursos desta API. Por meio da API Flux Tasks, você pode facilmente consultar o status de execução das tarefas da API Flux Images Generation. Para um exemplo completo de envio e polling de vídeos, consulte o Guia de integração da API Flux Videos. A consulta de tarefas existentes não gera custos adicionais de geração.

Processo de solicitação

Para usar a API Flux Images Generation, primeiro obtenha seu API Token no Console Ace Data Cloud e guarde-o para uso posterior.

Se você ainda não estiver conectado ou registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e fazer login; após a conclusão, você retornará automaticamente para a página atual. Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar separadamente para cada serviço. A primeira solicitação oferece créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo universal no console.

📘 Documentação completa: API Flux Images Generation →

Exemplo de solicitação

A API Flux Tasks pode ser usada para consultar os resultados da API Flux Images Generation. Para saber como usar a API Flux Images Generation, consulte a documentação API Flux Images Generation. Usaremos como exemplo um ID de tarefa retornado pelo serviço API Flux Images Generation, demonstrando como usar esta API. Suponha que temos um ID de tarefa: 2db0168c-2373-4367-8d9a-9dc778802e8a, a seguir demonstraremos como por meio da passagem de um ID de tarefa.

Imagem de exemplo da tarefa

Configurar cabeçalhos e corpo da solicitação

Request Headers incluem:

accept: especifica que os resultados de resposta recebidos estão no formato JSON, aqui preencha com application/json.
authorization: a chave para chamar a API, após a solicitação você pode selecioná-la diretamente no menu suspenso.

Request Body inclui:

id: o ID da tarefa enviada.
action: o modo de operação da tarefa.

Configure conforme mostrado na imagem abaixo:

Exemplo de código

É possível observar que vários códigos em diferentes linguagens já foram gerados automaticamente no lado direito da página, conforme mostrado na imagem:

Alguns exemplos de código são os seguintes:

CURL

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "2c454ff3-4f8f-47f0-8147-acb29a84d1c2",
  "action": "retrieve"
}'

Python

import requests

url = "https://api.acedata.cloud/flux/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "2c454ff3-4f8f-47f0-8147-acb29a84d1c2",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Exemplo de resposta

Após a solicitação ser bem-sucedida, a API retornará as informações detalhadas da tarefa de imagem aqui. Por exemplo:

{
  "_id": "677de81d550a4144a5f4cf62",
  "id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
  "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
  "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
  "created_at": 1736304669.779,
  "started_at": 1736304669.839,
  "finished_at": 1736304679.439,
  "elapsed": 9.6,
  "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
  "request": {
    "action": "generate",
    "size": "1024x1024",
    "prompt": "a white siamese cat"
  },
  "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
    "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
    "data": [
      {
        "prompt": "a white siamese cat",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "seed": 281520112,
        "timings": {
          "inference": 3.193
        }
      }
    ]
  }
}

O resultado retornado possui vários campos. O campo request é o request body ao iniciar a tarefa, enquanto o campo response é o response body retornado após a conclusão da tarefa. A descrição dos campos é a seguinte.

id, o ID que gera esta tarefa de imagem, usado para identificar exclusivamente esta tarefa de geração de imagem.
request, as informações da solicitação na consulta da tarefa de imagem.
response, as informações de retorno na consulta da tarefa de imagem.
created_at, hora de criação da tarefa, timestamp Unix (segundos, ponto flutuante).
started_at, hora de início da execução da tarefa, timestamp Unix (segundos, ponto flutuante).
finished_at, hora de conclusão da tarefa, timestamp Unix (segundos, ponto flutuante). Este campo não é retornado quando a tarefa não foi concluída.
elapsed, tempo de execução da tarefa, em segundos (ponto flutuante, com 3 casas decimais). Este campo não é retornado quando a tarefa não foi concluída.

Operação de consulta em lote

Isto é para consultar os detalhes de tarefas de imagem para vários IDs de tarefa. A diferença em relação ao acima é que é necessário selecionar retrieve_batch como action. Request Body inclui:

ids: o array de IDs de tarefas enviadas.
action: o modo de operação da tarefa.

Configure conforme mostrado na imagem abaixo:

Exemplo de código

É possível observar que vários códigos em diferentes linguagens já foram gerados automaticamente no lado direito da página, conforme mostrado na imagem:

Alguns exemplos de código são os seguintes:

Exemplo de resposta

Após a solicitação ser bem-sucedida, a API retornará informações detalhadas específicas de todas as tarefas de imagem em lote desta vez. Por exemplo:

{
  "items": [
    {
      "_id": "677de81d550a4144a5f4cf62",
      "id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
      "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
      "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
      "created_at": 1736304669.779,
      "started_at": 1736304669.839,
      "finished_at": 1736304679.439,
      "elapsed": 9.6,
      "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
      "request": {
        "action": "generate",
        "size": "1024x1024",
        "prompt": "um gato siamês branco"
      },
      "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
        "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
        "data": [
          {
            "prompt": "um gato siamês branco",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "seed": 281520112,
            "timings": {
              "inference": 3.193
            }
          }
        ]
      }
    },
    {
      "_id": "677de950550a4144a5f52963",
      "id": "72bdd69d-290d-4710-a6d4-60c78968865a",
      "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
      "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
      "created_at": 1736304976.278,
      "started_at": 1736304976.338,
      "finished_at": 1736304985.938,
      "elapsed": 9.6,
      "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
      "request": {
        "action": "generate",
        "size": "1024x1024",
        "prompt": "um gato siamês branco"
      },
      "trace_id": "1dca4b49-d31d-42e6-83d9-7f0c56f62d31",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "72bdd69d-290d-4710-a6d4-60c78968865a",
        "trace_id": "1dca4b49-d31d-42e6-83d9-7f0c56f62d31",
        "data": [
          {
            "prompt": "um gato siamês branco",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "seed": 1437672535,
            "timings": {
              "inference": 3.175
            }
          }
        ]
      }
    }
  ],
  "count": 2
}

O resultado retornado possui vários campos no total, entre os quais items contém as informações detalhadas específicas das tarefas de imagens em lote. As informações específicas de cada tarefa de imagem são iguais aos campos acima, e as informações dos campos são as seguintes.

items, todas as informações detalhadas específicas das tarefas de imagens em lote. É um array, e cada elemento do array tem o mesmo formato do resultado retornado da consulta de uma única tarefa acima.
count, o número de tarefas de imagem consultadas em lote aqui.

CURL

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["2db0168c-2373-4367-8d9a-9dc778802e8a","72bdd69d-290d-4710-a6d4-60c78968865a"],
  "action": "retrieve_batch"
}'

Python

import requests

url = "https://api.acedata.cloud/flux/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "ids": ["2db0168c-2373-4367-8d9a-9dc778802e8a","72bdd69d-290d-4710-a6d4-60c78968865a"],
    "action": "retrieve_batch"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e as informações de erro correspondentes. Por exemplo:

400 token_mismatched：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token：Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests：Muitas solicitações, você excedeu o limite de taxa.
500 api_error：Erro interno do servidor, algo deu errado no servidor.

Exemplo de resposta de erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Por meio deste documento, você já aprendeu como usar a API FLux Tasks para consultar todas as informações detalhadas específicas de tarefas de imagem únicas ou em lote. Esperamos que este documento possa ajudá-lo a integrar e usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Integração e uso da API Flux Tasks

Processo de solicitação

Exemplo de solicitação

Imagem de exemplo da tarefa

Configurar cabeçalhos e corpo da solicitação

Exemplo de código

CURL

Python

Exemplo de resposta

Operação de consulta em lote

Exemplo de código

Exemplo de resposta

CURL

Python

Tratamento de erros

Exemplo de resposta de erro

Conclusão

​Processo de solicitação

​Exemplo de solicitação

​Imagem de exemplo da tarefa

​Configurar cabeçalhos e corpo da solicitação

​Exemplo de código

​CURL

​Python

​Exemplo de resposta

​Operação de consulta em lote

​Exemplo de código

​Exemplo de resposta

​CURL

​Python

​Tratamento de erros

​Exemplo de resposta de erro

​Conclusão

Processo de solicitação

Exemplo de solicitação

Imagem de exemplo da tarefa

Configurar cabeçalhos e corpo da solicitação

Exemplo de código

CURL

Python

Exemplo de resposta

Operação de consulta em lote

Exemplo de código

Exemplo de resposta

CURL

Python

Tratamento de erros

Exemplo de resposta de erro

Conclusão