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

# Geração de imagens MiniMax-H3-Image-Highspeed

>  - Usa o modelo rápido minimax-h3-image-highspeed, que gera imagens mais rápido, com parâmetros idênticos aos da versão padrão
- Processamento assíncrono com task_id para consultar o resultado
- Texto para imagem e edição com até 16 imagens de referência
- Até 10 imagens por solicitação, com otimização de prompt integrada (pode ser desativada)
- Níveis 1K / 2K / 4K + proporção, ou dimensões exatas em pixels (até 20 megapixels) 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image-highspeed",
    "prompt": "Café à beira-mar ao entardecer, fotografia realista, tons quentes",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "minimax-h3-image-highspeed",
        "prompt": "Café à beira-mar ao entardecer, fotografia realista, tons quentes",
        "size": "16:9",
        "resolution": "2K",
        "n": 1,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "minimax-h3-image-highspeed",
      prompt: "Café à beira-mar ao entardecer, fotografia realista, tons quentes",
      size: "16:9",
      resolution: "2K",
      n: 1,
    }),
  },
);

console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Parâmetros de solicitação inválidos",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Falha na autenticação. Verifique sua chave de API.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Saldo insuficiente",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Requisições muito frequentes, tente novamente mais tarde",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "Erro interno do servidor, tente novamente mais tarde",
    "type": "server_error"
  }
}
```

## Autenticação

**Authorization** `string` *required*

Todos os endpoints usam Bearer Token. Obtenha sua chave na [página de chaves de API](https://apimart.ai/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Sobre os modelos

| Modelo | Características | Casos de uso |
| - | - | - |
| `minimax-h3-image-highspeed` | Versão rápida, gera mais rápido; preço de entrada / saída de imagem 2 vezes o da versão padrão | Cenários sensíveis à latência, geração interativa |
| `minimax-h3-image` | Versão padrão, preço unitário menor | Geração em lote; veja [MiniMax-H3-Image](https://docs.apimart.ai/pt/api-reference/images/minimax-h3-image/generation.md) |

O MiniMax H3 Image se destaca em fotografia realista, pôsteres, imagens de produto e cenas com texto. Por padrão, ele expande automaticamente o prompt em uma descrição detalhada da cena antes de gerar a imagem. O texto expandido aparece em `revised_prompt` no resultado da consulta. Para gerar seguindo exatamente o texto original, veja [Desativar a otimização do prompt](#desativar-a-otimização-do-prompt).

> [!WARNING]
>
> Sem `resolution`, a saída padrão é **4K** (cerca de 16 megapixels), com preço unitário cerca de 3,6 vezes o de 1K / 2K. Se não precisar de 4K, envie explicitamente `"resolution": "2K"`.

## Parâmetros da solicitação

**model** `string` *required*

Nome do modelo de geração de imagens, fixo em `minimax-h3-image-highspeed`.

**prompt** `string` *required*

Descrição em texto da imagem a gerar ou editar.

Aceita chinês e inglês. Após remover espaços no início e no fim, deve ter de `1` a `32,000` caracteres.

**image\_urls** `string[]`

Array de imagens de referência, no máximo `16`. Quando enviado, ativa automaticamente o modo de edição.

Cada item pode ser um link direto `http(s)://` acessível publicamente ou Base64 inline no formato `data:image/png;base64,...` (a plataforma converte em link antes de enviar ao modelo).

Veja [Requisitos das imagens de referência](#requisitos-das-imagens-de-referência).

**size** `string` (default: auto)

Proporção ou dimensões exatas em pixels da imagem de saída.

Valores aceitos:

* `auto`: o modelo decide a composição e a proporção com base no prompt
* Proporção: formato `X:Y`, com X e Y inteiros de `1` a `300` e proporção entre `1:3` e `3:1` (inclusive), como `1:1`, `4:3`, `16:9`, `9:16`, `3:1`
* Pixels exatos: `larguraxaltura`, como `2048x1152` (também aceita os separadores `X`, `×`, `*`)

Veja [Regras de tamanho](#regras-de-tamanho).

**resolution** `string` (default: 4K)

Nível de resolução; junto com a proporção, define os pixels reais da saída.

* `1K`: cerca de 1 megapixel
* `2K`: cerca de 4,2 megapixels
* `4K` (padrão): cerca de 16 megapixels

Também aceita minúsculas.

> [!WARNING]
>
> Quando `size` usa pixels exatos, **não** envie `resolution`; caso contrário, retorna 400.

**n** `integer` (default: 1)

Quantidade de imagens a gerar, de `1` a `10`.

**prompt\_optimizer** `boolean` (default: true)

Se o prompt deve ser expandido automaticamente.

`false` só vale para texto para imagem e exige um tamanho explícito; veja [Desativar a otimização do prompt](#desativar-a-otimização-do-prompt).

**output\_format** `string` (default: jpeg)

Formato do arquivo de saída.

* `jpeg` (padrão; também aceita `jpg`)
* `png`
* `webp`

**output\_compression** `integer` (default: 95)

Qualidade de compressão, de `0` a `100`. Não se aplica a `png`.

**watermark** `boolean` (default: false)

Se deve adicionar à imagem uma marca d'água visível de conteúdo gerado por IA. Não afeta a identificação implícita nos metadados da imagem.

> [!NOTE]
>
> Os parâmetros a seguir não são suportados e são ignorados se enviados: `quality`, `style`, `seed`, `negative_prompt`, `background`, `mask_url`.
>
> Os resultados são sempre retornados como URL; enviar `response_format: "b64_json"` retorna 400.

## Regras de tamanho

| Você quer | Envie assim |
| - | - |
| Padrão (4K, proporção escolhida pelo modelo) | Não envie parâmetros de tamanho |
| Nível + proporção | `size: "16:9"`, `resolution: "2K"` |
| Controlar só o nível, com proporção decidida pelo modelo | `resolution: "1K"` (omita `size` ou envie `auto`) |
| Controle exato em pixels | `size: "2048x1152"` (**não envie `resolution`**) |

### Nível + proporção

O nível define a área total e a proporção define o formato:

| Nível | Área alvo | Exemplo de saída real |
| - | - | - |
| `1K` | cerca de 1024×1024 (cerca de 1 megapixel) | Proporção automática → 1184×880 |
| `2K` | cerca de 2048×2048 (cerca de 4,2 megapixels) | `1:1` → 2048×2048 |
| `4K` (padrão) | cerca de 4096×4096 (cerca de 16 megapixels) | Proporção automática → 3552×4736 |

Os pixels reais da saída são arredondados pelo modelo com base na proporção e no nível; considere o valor retornado. Para dimensões exatas, use o formato em pixels.

### Pixels exatos

Ao usar `size: "larguraxaltura"`, as seguintes condições devem ser atendidas:

| Restrição | Valor |
| - | - |
| Total de pixels (largura × altura) | `655,360` \~ `20,000,000` |
| Proporção | `1:3` \~ `3:1` |
| Com `resolution` | Não podem ser enviados juntos |

* ✅ `1024x1024`, `2048x1152`, `1536x1536`, `4000x5000`
* ❌ `512x512` (área pequena demais), `4000x1000` (proporção acima de 3:1), `5000x5000` (acima de 20 megapixels)

## Requisitos das imagens de referência

| Item | Requisito |
| - | - |
| Quantidade | No máximo 16 |
| Formato | JPG / JPEG / PNG / WebP / HEIC / HEIF (GIF não é suportado) |
| Tamanho por imagem | Até 64 MB |
| Dimensões por imagem | Cada lado entre 128 e 8192 pixels; lado maior ÷ lado menor ≤ 4 |

> [!WARNING]
>
> Ao usar URLs, garanta que o link seja **acessível publicamente**. Se o link não puder ser acessado, a tarefa falha na etapa de geração (`status` igual a `failed`, com reembolso integral).
>
> No modo de edição, a otimização do prompt fica sempre ativa e não pode ser desativada.

## Desativar a otimização do prompt

Por padrão, o modelo expande o prompt antes de gerar a imagem. Para gerar seguindo exatamente o texto original, envie `"prompt_optimizer": false`, desde que:

* Seja usado apenas em **texto para imagem**; com `image_urls`, retorna 400
* O **tamanho seja explícito**: `size` deve ser uma proporção (como `1:1`) ou pixels (como `1024x1024`), não `auto` nem omitido

Com a otimização desativada, o modelo lê apenas cerca dos primeiros 4096 tokens do prompt.

## Response

**code** `integer`

Código de resposta; 200 quando o envio é bem-sucedido.

**data** `array`

Dados da resposta do envio.

**Item do array**

**status** `string`

Estado inicial: `submitted`.

**task\_id** `string`

Identificador exclusivo da tarefa, usado para consultar o status e o resultado.

## Resposta do envio

Após o envio bem-sucedido, o ID da tarefa assíncrona é retornado imediatamente:

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## Consultar o resultado da tarefa

Use o `task_id` da resposta do envio para chamar a [API de consulta de tarefas](https://docs.apimart.ai/pt/api-reference/tasks/status.md):

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

A versão rápida gera imagens mais rápido que a padrão (em testes, a versão padrão leva cerca de 10 a 20 segundos por imagem 1K / 2K e cerca de 20 segundos em 4K). Recomendamos consultar a cada 3 a 5 segundos até o status mudar para `completed` ou `failed`. Uma tarefa pode rodar por até 600 segundos; defina o timeout de polling do cliente em 10 minutos.

### Tarefa concluída

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "created": 1794450409,
    "completed": 1794450428,
    "actual_time": 19,
    "estimated_time": 60,
    "cost": 0.0493,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example_0.jpeg",
            "https://upload.apimart.ai/f/image/example_1.jpeg"
          ],
          "expires_at": 1794536828,
          "revised_prompt": "The image is a realistic, close-up still life photograph of ...",
          "revised_prompts": [
            "The image is a realistic ...",
            "The image is a professional ..."
          ]
        }
      ]
    }
  }
}
```

As URLs das imagens ficam em `data.result.images[0].url[]`, com todas as `n` imagens nesse único array. Baixe e armazene antes de `expires_at`. Se a tarefa falhar, `status` será `failed`, o motivo estará em `error.message` e o valor será reembolsado integralmente de forma automática.

## Exemplos de uso

### Texto para imagem (4K padrão)

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "A cozy coffee shop by the sea at sunset, photorealistic, warm tones"
}
```

### Texto para imagem (1K + proporção, 4 imagens)

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Foto de produto de fones de ouvido em estilo minimalista, fundo branco, sombras suaves",
  "size": "1:1",
  "resolution": "1K",
  "n": 4
}
```

### Pixels exatos + PNG

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Pôster de cidade à noite, luzes de neon, estilo cyberpunk, com o título NIGHT CITY",
  "size": "2048x1152",
  "output_format": "png"
}
```

### Edição com imagens de referência

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Vista na pessoa da primeira imagem a jaqueta da segunda imagem, mantendo o fundo inalterado",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/jacket.png"
  ],
  "resolution": "2K"
}
```

### Desativar a otimização do prompt

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "a red apple on a wooden table, top view",
  "size": "1:1",
  "resolution": "1K",
  "prompt_optimizer": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.