Flux Images Generation API Integração

Este documento irá apresentar uma descrição da integração da API de Geração de Imagens Flux, que pode gerar imagens oficiais da Flux através da entrada de parâmetros personalizados.

Processo de Solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da API de Geração de Imagens Flux para solicitar o serviço correspondente. Após entrar na página, clique no botão “Adquirir”, conforme mostrado na imagem:

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

Uso Básico

Primeiro, entenda a forma básica de uso, que é inserir a palavra-chave prompt, a ação action, e o tamanho da imagem size, para obter o resultado processado. Primeiro, é necessário passar um campo action, cujo valor é generate, e então precisamos inserir a palavra-chave, conforme o conteúdo abaixo:

Podemos ver que aqui configuramos os Headers da Requisição, incluindo:

accept: o formato de resposta desejado, aqui preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Requisição, incluindo:

action: a ação da tarefa de geração de imagem.
size: o tamanho do resultado da geração da imagem.
count: a quantidade de imagens a serem geradas, o valor padrão é 1, este parâmetro é válido apenas para tarefas de geração de imagens, não é válido para tarefas de edição.
prompt: a palavra-chave.
model: o modelo de geração, padrão flux-dev.
callback_url: a URL para onde os resultados devem ser retornados.

O parâmetro size tem algumas restrições especiais, que se dividem em dois tipos: proporção largura x altura width x height e proporção de imagem x:y, conforme detalhado abaixo:

Modelo	Faixa
flux-2-flex	Suporta proporção largura x altura x >= 64 deve ser múltiplo de 32
flux-2-pro	Suporta proporção largura x altura x >= 64 deve ser múltiplo de 32
flux-2-max	Suporta proporção largura x altura x >= 64 deve ser múltiplo de 32
flux-pro-1.1	Suporta proporção largura x altura 256 <= x <= 1440 deve ser múltiplo de 32
flux-dev	Suporta proporção largura x altura 256 <= x <= 1440 deve ser múltiplo de 32
flux-pro-1.1-ultra	Não suporta proporção largura x altura, suporta proporção de imagem
flux-kontext-pro	Não suporta proporção largura x altura, suporta proporção de imagem
flux-kontext-max	Não suporta proporção largura x altura, suporta proporção de imagem

Proporções de imagem de referência: “1:1”, “16:9”, “21:9”, “3:2”, “2:3”, “4:5”, “5:4”, “3:4”, “4:3”, “9:16”, “9:21”, Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Tentar” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado:

{
  "success": true,
  "task_id": "226eb763-9eab-4d06-ad57-d59753a03307",
  "trace_id": "089f8b46-0167-4f25-88ee-3c3f88d80e84",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/lion/NVhtlwwGYQD6HrGaEfrzu_341484fad6d84b21b73f4f8824a3f98a.png",
      "timings": 1752743801
    },
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/8UEQpFbQCYVOK1wKP3aV0_9bbc26fad64049b18d0244b99ef66ad1.png",
      "timings": 1752743801
    }
  ]
}

O resultado retornado contém vários campos, descritos a seguir:

success, o status da tarefa de geração de vídeo neste momento.
task_id, o ID da tarefa de geração de vídeo neste momento.
trace_id, o ID de rastreamento da geração de vídeo neste momento.
data, a lista de resultados da tarefa de geração de imagem neste momento.
- image_url, o link da tarefa de geração de imagem neste momento.
- prompt, a palavra-chave.

Podemos ver que obtivemos informações de imagem satisfatórias, e precisamos apenas acessar o link da imagem gerada no data para obter a imagem Flux gerada. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, como o código CURL abaixo:

curl -X POST 'https://api.xhuoapi.ai/v1/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "a white siamese cat",
  "model": "flux-kontext-pro",
  "count": 2
}'

Edição de Tarefas de Imagem

Se você quiser editar uma imagem específica, primeiro o parâmetro image_url deve conter o link da imagem que precisa ser editada, neste caso, action só suporta edit, e você pode especificar o seguinte conteúdo:

model: o modelo utilizado para a tarefa de edição de imagem, atualmente suportando flux-kontext-max, flux-kontext-pro.
image_url: o link da imagem que precisa ser editada.

Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

O código correspondente:

import requests

url = "https://api.xhuoapi.ai/v1/flux/images"

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

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.xhuoapi.ai/ytj2qy.png"
}

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

Ao clicar em executar, você pode notar que receberá imediatamente um resultado, conforme abaixo:

{
  "success": true,
  "task_id": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/aEUXJZ6Faj9YXUCQVs01Q_af0cea56c558441c9ba8df67b200812d.png",
      "timings": 1752744073
    }
  ]
}

Podemos ver que o efeito gerado é uma edição da imagem original, e o resultado é semelhante ao mencionado anteriormente.

Callback Assíncrono

由于 Flux Images Generation API gera um tempo relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em um consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo callback_url adicional. Após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, contendo um campo de informação task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da imagem gerada será enviado para o callback_url especificado pelo cliente, em formato JSON POST, que também incluirá o campo task_id, assim o resultado da tarefa pode ser associado pelo ID. Abaixo, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Aqui, para facilitar a demonstração, usamos um site de exemplo de Webhook público https://webhook.site/, ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem:

Copie esta URL, que pode ser usada como Webhook, o exemplo aqui é https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Em seguida, podemos definir o campo callback_url para a URL do Webhook acima, enquanto preenchemos os parâmetros correspondentes, o conteúdo específico é mostrado na imagem:

Clique em executar, e você verá que receberá imediatamente um resultado, como abaixo:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Aguarde um momento, e você poderá observar o resultado da imagem gerada em https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, como mostrado na imagem:

O conteúdo é o seguinte:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/f4f8d407-377a-408a-82d0-427a5a836f09_0.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}

Pode-se ver que o resultado contém um campo task_id, e os outros campos são semelhantes ao mencionado anteriormente, através deste campo é possível realizar a associação da tarefa.

Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. 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

Através deste documento, você já entendeu como usar a API de Geração de Imagens Flux para gerar imagens através da entrada de palavras-chave. 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.

Documentation Index

​Processo de Solicitação

​Uso Básico

​Edição de Tarefas de Imagem

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão