Skip to main content
Este documento irá apresentar uma integração com a 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 de Geração de Imagens Flux, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro. Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar. Após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no painel de controle.
📘 Documentação Completa: Flux Images Generation API →

​
Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em 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 deve ser generate, e em seguida, precisamos inserir a palavra-chave, conforme o conteúdo abaixo:

Aqui, podemos ver que configuramos os Cabeçalhos da Solicitação, incluindo:
  • accept: o formato de resposta desejado, que deve ser 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 Solicitação, incluindo:
  • action: a ação da tarefa de geração de imagem.
  • size: o tamanho do resultado da imagem gerada. As séries flux-2-flex / flux-2-pro / flux-2-max devem ter a proporção da imagem informada (como 1:1, 16:9), não aceitando tamanhos em pixels como 1024x1024, e a omissão retornará 400.
  • count: a quantidade de imagens a serem geradas, cujo valor padrão é 1; este parâmetro é válido apenas para tarefas de geração de imagens, não sendo válido para tarefas de edição.
  • prompt: a palavra-chave.
  • model: o modelo de geração, padrão flux-dev; o modelo mais recente é flux-2-pro, flux-2-max (com qualidade de imagem superior, deve ser combinado com a proporção da imagem size).
  • callback_url: a URL que precisa receber o resultado.
  • async: opcional, se definido como true, a interface retorna imediatamente task_id, sem necessidade de fornecer callback_url, e posteriormente, você pode consultar o resultado através da interface de consulta de tarefas correspondente.
O parâmetro size possui algumas restrições especiais, divididas principalmente em dois tipos: proporção width x height e proporção x:y, conforme detalhado abaixo: Proporções de imagem de referência: “21:9”, “16:9”, “4:3”, “3:2”, “1:1”, “2:3”, “3:4”, “9:16”, “9:21”. Após selecionar os parâmetros, o código correspondente será gerado automaticamente à direita. Antes de copiar, verifique se o cabeçalho de autorização está usando sua própria chave de API; credenciais reais não devem aparecer na documentação e nas capturas de tela. Clique no botão “Try” para realizar o teste, e aqui obtivemos o seguinte resultado:
O resultado retornado possui vários campos, conforme descrito abaixo:
  • success, o estado atual da tarefa de geração de vídeo.
  • task_id, o ID da tarefa de geração de vídeo.
  • trace_id, o ID de rastreamento da geração de vídeo.
  • data, a lista de resultados da tarefa de geração de imagem.
    • image_url, o link da tarefa de geração de imagem.
    • prompt, a palavra-chave.
Podemos ver que obtivemos informações satisfatórias sobre a imagem, e precisamos apenas acessar o link da imagem gerada em data para obter a imagem Flux. Além disso, se você quiser gerar o código correspondente para a integração, pode copiá-lo diretamente, como o código CURL abaixo:

​
Edição de Tarefas de Imagem

Se você deseja editar uma imagem específica, primeiro o parâmetro image_url deve conter o link da imagem a ser editada, e neste caso, action deve ser definido como edit, permitindo especificar o seguinte conteúdo:
  • model: o modelo utilizado para a tarefa de edição de imagem, suportando flux-dev, flux-pro, flux-kontext-pro, flux-kontext-max, flux-2-flex, flux-2-pro, flux-2-max.
  • image_url: o link da imagem a ser editada.
Um exemplo de preenchimento é o seguinte:

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

O código correspondente:
Ao clicar em executar, você verá que um resultado será imediatamente obtido, conforme abaixo:
可以看到，生成的效果是对原图片进行编辑的效果，结果与上文类似。

​
异步回调

由于 Flux Images Generation API 生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。 整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。 下面我们通过示例来了解下具体怎样操作。 首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示： 将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。 接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下：
稍等片刻，我们可以在 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab 上观察到生成图片的结果，如图所示： 内容如下：
可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token：Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests：Too many requests, you have exceeded the rate limit.
  • 500 api_error：Internal server error, something went wrong on the server.

​
错误响应示例

​
结论

通过本文档，您已经了解了如何使用 Flux Images Generation API 可通过输入提示词来生成图片。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。