> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Flux Images Generation API Integração

> Flux Image Generation API guide - Ace Data Cloud

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](https://platform.acedata.cloud/documents/flux-images) para solicitar o serviço correspondente. Após entrar na página, clique no botão "Adquirir", conforme mostrado na imagem:

![](https://cdn.acedata.cloud/q6ytrc.png)

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:

<p>
  <img src="https://cdn.acedata.cloud/wz85jt.png" width="500" className="m-auto" />
</p>

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:

<p>
  <img src="https://cdn.acedata.cloud/8q7aux.png" width="500" className="m-auto" />
</p>

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

```json theme={null}
{
  "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:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/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:

<p>
  <img src="https://cdn.acedata.cloud/jn9da5.png" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.acedata.cloud/6cwxb8.png" width="500" className="m-auto" />
</p>

O código correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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:

```json theme={null}
{
  "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/](https://webhook.site/), ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem:

![](https://cdn.acedata.cloud/cjjfly.png)

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:

<p>
  <img src="https://cdn.acedata.cloud/wm6caw.png" width="500" className="m-auto" />
</p>

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:

![](https://cdn.acedata.cloud/v23lot.png)

O conteúdo é o seguinte:

```json theme={null}
{
  "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

```json theme={null}
{
  "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.