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

# Flux Images Generation API Integração

> Flux Image Generation 集成指南 - XHuoAPI

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://api.xhuoapi.ai/documents/6b9197c5-7a3f-4878-a43f-7f94e7e66394) para solicitar o serviço correspondente. Após entrar na página, clique no botão "Adquirir", conforme mostrado na imagem:

![](https://cdn.xhuoapi.ai/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.xhuoapi.ai/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.xhuoapi.ai/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.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:

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

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

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

O código correspondente:

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

```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.xhuoapi.ai/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.xhuoapi.ai/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.xhuoapi.ai/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.