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

# Gerar e Editar Imagens com Modelos GPT e Gemini via Flatkey

> Gere e edite imagens pelo Flatkey com gpt-image-2 e modelos de imagem Gemini, usando APIs compatíveis com OpenAI Images ou a API nativa do Gemini.

O Flatkey oferece duas famílias de APIs de imagem. Use os endpoints `/v1/images/generations` e `/v1/images/edits` compatíveis com OpenAI para `gpt-image-2`. Use o endpoint nativo `generateContent` do Gemini para modelos de imagem Gemini.

<Warning>
  Não é possível chamar modelos de imagem Gemini com o SDK OpenAI Images, `/v1/images/generations` ou `/v1/images/edits`. Use os exemplos da API nativa do Gemini nesta página. Caso contrário, a requisição pode retornar `get_channel_failed`.
</Warning>

## Modelos de imagem suportados

| Modelo                        | API                  | Preço oficial      | Preço com bônus      |
| ----------------------------- | -------------------- | ------------------ | -------------------- |
| `gpt-image-2`                 | OpenAI Images API    | \$6,65 / 1M tokens | \~\$3,99 / 1M tokens |
| `gemini-3-pro-image`          | API nativa do Gemini | \$2,00 / 1M tokens | \~\$1,20 / 1M tokens |
| `gemini-2.5-flash-image`      | API nativa do Gemini | \$0,30 / 1M tokens | \~\$0,18 / 1M tokens |
| `gemini-3.1-flash-image`      | API nativa do Gemini | Consulte o painel  | Consulte o painel    |
| `gemini-3.1-flash-lite-image` | API nativa do Gemini | Consulte o painel  | Consulte o painel    |
| `nano-banana-pro-preview`     | API nativa do Gemini | Consulte o painel  | Consulte o painel    |

Consulte o [Diretório de Modelos](https://flatkey.ai/models) para a lista completa de modelos e preços atuais.

## Usar gpt-image-2

### Usar o SDK da OpenAI

<CodeGroup>
  ```python python theme={"dark"}
  import base64
  import os
  from pathlib import Path

  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["FLATKEY_API_KEY"],
      base_url="https://router.flatkey.ai/v1",
  )

  response = client.images.generate(
      model="gpt-image-2",
      prompt="A serene mountain lake at sunset, photorealistic",
      size="1024x1024",
  )

  Path("generated.png").write_bytes(
      base64.b64decode(response.data[0].b64_json)
  )
  ```

  ```javascript node theme={"dark"}
  import { writeFileSync } from "node:fs";
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: "https://router.flatkey.ai/v1",
  });

  const response = await client.images.generate({
    model: "gpt-image-2",
    prompt: "A serene mountain lake at sunset, photorealistic",
    size: "1024x1024",
  });

  writeFileSync(
    "generated.png",
    Buffer.from(response.data[0].b64_json, "base64"),
  );
  ```
</CodeGroup>

### Gerar uma imagem com curl

```bash theme={"dark"}
curl https://router.flatkey.ai/v1/images/generations \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic cityscape at night, neon lights, wide angle",
    "size": "1024x1024"
  }'
```

Este endpoint retorna a imagem gerada em `data[0].b64_json`; `gpt-image-2` não fornece uma URL de imagem hospedada. Consulte a [referência da API de Imagens](/pt/api-reference/image-generation#gerar-uma-imagem) para todos os campos.

### Editar uma imagem com curl

Use `/v1/images/edits` para enviar uma imagem de entrada junto com instruções de edição. Este endpoint usa `multipart/form-data`; `image` é obrigatório e `mask` é opcional.

```bash theme={"dark"}
curl https://router.flatkey.ai/v1/images/edits \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=add a small yellow star in the center" \
  -F "image=@input.png" \
  -F "mask=@mask.png"
```

`image` suporta PNG, JPEG e WebP. Omita `mask` para editar a imagem inteira com base no prompt. Quando uma máscara é fornecida, suas áreas transparentes identificam as regiões a redesenhar. A imagem editada é retornada em `data[0].b64_json`. Consulte a [referência da API de edição](/pt/api-reference/image-generation#editar-uma-imagem) para todos os campos.

## Usar modelos de imagem Gemini

Os modelos de imagem Gemini usam o endpoint a seguir. Substitua `{model}` por um ID de modelo:

```text theme={"dark"}
POST https://router.flatkey.ai/v1beta/models/{model}:generateContent
```

A requisição deve incluir `"IMAGE"` em `generationConfig.responseModalities`. As imagens geradas são retornadas em `candidates[].content.parts[].inlineData`.

### Usar curl

```bash theme={"dark"}
curl https://router.flatkey.ai/v1beta/models/gemini-2.5-flash-image:generateContent \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "A product photo of a translucent purple glass bottle on a white background"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'
```

### Usar Python e salvar a imagem

Instale um cliente HTTP:

```bash theme={"dark"}
pip install requests
```

```python theme={"dark"}
import base64
import os
from pathlib import Path

import requests

model = "gemini-2.5-flash-image"
response = requests.post(
    f"https://router.flatkey.ai/v1beta/models/{model}:generateContent",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [{
                "text": "A product photo of a translucent purple glass bottle on a white background"
            }]
        }],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"]
        },
    },
    timeout=180,
)
response.raise_for_status()

parts = response.json()["candidates"][0]["content"]["parts"]
image = next(part["inlineData"] for part in parts if "inlineData" in part)
suffix = ".jpg" if image["mimeType"] == "image/jpeg" else ".png"
output = Path(f"generated{suffix}")
output.write_bytes(base64.b64decode(image["data"]))
print(output)
```

### Usar Node.js e salvar a imagem

```javascript theme={"dark"}
import { writeFileSync } from "node:fs";

const model = "gemini-2.5-flash-image";
const response = await fetch(
  `https://router.flatkey.ai/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [{
          text: "A product photo of a translucent purple glass bottle on a white background",
        }],
      }],
      generationConfig: {
        responseModalities: ["TEXT", "IMAGE"],
      },
    }),
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

const result = await response.json();
const image = result.candidates[0].content.parts.find(
  (part) => part.inlineData,
).inlineData;
const suffix = image.mimeType === "image/jpeg" ? "jpg" : "png";
writeFileSync(`generated.${suffix}`, Buffer.from(image.data, "base64"));
```

## Campos da requisição Gemini

<ParamField body="contents" type="array" required>
  Conteúdo da conversa. Para geração de imagem a partir de texto, coloque a descrição da imagem em `parts[].text`.
</ParamField>

<ParamField body="generationConfig.responseModalities" type="array" required>
  Modalidades de resposta. Use `["TEXT", "IMAGE"]` para texto e imagens, ou `["IMAGE"]` para solicitar apenas imagens.
</ParamField>

<ParamField body="model" type="string" required>
  O ID do modelo aparece no caminho da URL, não no corpo da requisição. Por exemplo, `gemini-3-pro-image`.
</ParamField>

## Formato de resposta do Gemini

```json theme={"dark"}
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is the generated image."
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAA..."
            }
          }
        ]
      }
    }
  ]
}
```

<Note>
  `inlineData.data` contém a imagem codificada em base64. Uma resposta pode conter texto e múltiplas partes de imagem. Itere sobre `parts` em vez de presumir que a imagem é sempre o primeiro item.
</Note>

## Solução de problemas

### A API retorna get\_channel\_failed

Certifique-se de que o endpoint corresponde ao modelo:

* Use `/v1/images/generations` para gerar com `gpt-image-2`.
* Use `/v1/images/edits` para editar com `gpt-image-2`.
* Use `/v1beta/models/{model}:generateContent` para modelos de imagem Gemini.

### A resposta do Gemini não contém uma imagem

Certifique-se de que `generationConfig.responseModalities` contém `"IMAGE"`. Verifique também a resposta em busca de erros ou bloqueio de segurança.

## Escrever prompts eficazes

* Especifique o estilo: *fotorrealista, pintura a óleo, aquarela, renderização 3D*
* Inclua detalhes de iluminação: *hora dourada, iluminação de estúdio, sombras dramáticas*
* Especifique a composição: *close-up, ângulo amplo, vista aérea, orientação retrato*
* Adicione modificadores de qualidade: *altamente detalhado, 4K, fotografia profissional*