> ## 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.

# Generación de imágenes MiniMax-H3-Image-Highspeed

>  - Usa el modelo rápido minimax-h3-image-highspeed, que genera imágenes más rápido con parámetros idénticos a los de la versión estándar
- Procesamiento asíncrono con task_id para consultar el resultado
- Texto a imagen y edición con hasta 16 imágenes de referencia
- Hasta 10 imágenes por solicitud, con optimización de prompt integrada (desactivable)
- Niveles 1K / 2K / 4K + relación de aspecto, o dimensiones exactas en píxeles (hasta 20 megapíxeles) 

```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": "Cafetería junto al mar al atardecer, fotografía realista, tonos cálidos",
    "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": "Cafetería junto al mar al atardecer, fotografía realista, tonos cálidos",
        "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: "Cafetería junto al mar al atardecer, fotografía realista, tonos cálidos",
      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 solicitud no válidos",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Error de autenticación. Comprueba tu clave de API.",
    "type": "authentication_error"
  }
}
```

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

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Peticiones demasiado frecuentes, inténtalo de nuevo más tarde",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "Error interno del servidor, inténtalo de nuevo más tarde",
    "type": "server_error"
  }
}
```

## Autenticación

**Authorization** `string` *required*

Todos los endpoints usan Bearer Token. Obtén tu clave en la [página de claves de API](https://apimart.ai/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Acerca de los modelos

| Modelo | Características | Casos de uso |
| - | - | - |
| `minimax-h3-image-highspeed` | Versión rápida, genera más rápido; precio de entrada / salida de imagen 2 veces el de la versión estándar | Escenarios sensibles a la latencia, generación interactiva |
| `minimax-h3-image` | Versión estándar, precio unitario más bajo | Generación por lotes; consulta [MiniMax-H3-Image](https://docs.apimart.ai/es/api-reference/images/minimax-h3-image/generation.md) |

MiniMax H3 Image destaca en fotografía realista, carteles, imágenes de producto y escenas con texto. De forma predeterminada, amplía automáticamente el prompt en una descripción detallada de la escena antes de generar la imagen. El texto ampliado se puede ver en `revised_prompt` en el resultado de la consulta. Para generar siguiendo exactamente el texto original, consulta [Desactivar la optimización del prompt](#desactivar-la-optimización-del-prompt).

> [!WARNING]
>
> Si no se envía `resolution`, la salida predeterminada es **4K** (unos 16 megapíxeles), con un precio unitario de aproximadamente 3,6 veces el de 1K / 2K. Si no necesitas 4K, envía explícitamente `"resolution": "2K"`.

## Parámetros de solicitud

**model** `string` *required*

Nombre del modelo de generación de imágenes, fijo en `minimax-h3-image-highspeed`.

**prompt** `string` *required*

Descripción en texto de la imagen que se generará o editará.

Admite chino e inglés. Tras eliminar los espacios al inicio y al final, debe tener entre `1` y `32,000` caracteres.

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

Array de imágenes de referencia, hasta `16`. Si se envía, se activa automáticamente el modo de edición.

Cada elemento puede ser un enlace directo `http(s)://` accesible públicamente o Base64 en línea con el formato `data:image/png;base64,...` (la plataforma lo convierte primero en un enlace antes de pasarlo al modelo).

Consulta [Requisitos de las imágenes de referencia](#requisitos-de-las-imágenes-de-referencia).

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

Relación de aspecto o dimensiones exactas en píxeles de la imagen de salida.

Valores admitidos:

* `auto`: el modelo decide la composición y la proporción según el prompt
* Relación de aspecto: formato `X:Y`, con X e Y enteros de `1` a `300` y una proporción entre `1:3` y `3:1` (ambos incluidos), como `1:1`, `4:3`, `16:9`, `9:16`, `3:1`
* Píxeles exactos: `anchoxalto`, como `2048x1152` (también admite los separadores `X`, `×`, `*`)

Consulta [Reglas de tamaño](#reglas-de-tamaño).

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

Nivel de resolución; junto con la relación de aspecto determina los píxeles reales de salida.

* `1K`: unos 1 megapíxel
* `2K`: unos 4,2 megapíxeles
* `4K` (predeterminado): unos 16 megapíxeles

También admite minúsculas.

> [!WARNING]
>
> Cuando `size` usa píxeles exactos, **no** se puede enviar `resolution`; de lo contrario, se devuelve 400.

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

Número de imágenes que se generarán, de `1` a `10`.

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

Indica si el prompt se amplía automáticamente.

`false` solo se aplica a texto a imagen y requiere indicar un tamaño explícito; consulta [Desactivar la optimización del prompt](#desactivar-la-optimización-del-prompt).

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

Formato del archivo de salida.

* `jpeg` (predeterminado; también se admite `jpg`)
* `png`
* `webp`

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

Calidad de compresión, de `0` a `100`. No se aplica a `png`.

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

Indica si se añade a la imagen una marca de agua visible de contenido generado por IA. No afecta a la identificación implícita en los metadatos de la imagen.

> [!NOTE]
>
> Los siguientes parámetros no se admiten y se ignoran si se envían: `quality`, `style`, `seed`, `negative_prompt`, `background`, `mask_url`.
>
> Los resultados siempre se devuelven como URL; enviar `response_format: "b64_json"` devuelve 400.

## Reglas de tamaño

| Lo que quieres | Cómo enviarlo |
| - | - |
| Predeterminado (4K, proporción elegida por el modelo) | No envíes parámetros de tamaño |
| Nivel + relación de aspecto | `size: "16:9"`, `resolution: "2K"` |
| Controlar solo el nivel, con proporción decidida por el modelo | `resolution: "1K"` (omite `size` o envía `auto`) |
| Control exacto en píxeles | `size: "2048x1152"` (**no envíes `resolution`**) |

### Nivel + relación de aspecto

El nivel determina el área total y la relación de aspecto determina la forma:

| Nivel | Área objetivo | Ejemplo de salida real |
| - | - | - |
| `1K` | unos 1024×1024 (unos 1 megapíxel) | Proporción automática → 1184×880 |
| `2K` | unos 2048×2048 (unos 4,2 megapíxeles) | `1:1` → 2048×2048 |
| `4K` (predeterminado) | unos 4096×4096 (unos 16 megapíxeles) | Proporción automática → 3552×4736 |

El modelo redondea los píxeles reales de salida según la proporción y el nivel; el valor devuelto es el que cuenta. Para dimensiones exactas, usa el formato en píxeles.

### Píxeles exactos

Al usar `size: "anchoxalto"`, deben cumplirse estas condiciones:

| Restricción | Valor |
| - | - |
| Total de píxeles (ancho × alto) | `655,360` \~ `20,000,000` |
| Relación de aspecto | `1:3` \~ `3:1` |
| Con `resolution` | No se pueden enviar juntos |

* ✅ `1024x1024`, `2048x1152`, `1536x1536`, `4000x5000`
* ❌ `512x512` (área demasiado pequeña), `4000x1000` (proporción superior a 3:1), `5000x5000` (más de 20 megapíxeles)

## Requisitos de las imágenes de referencia

| Elemento | Requisito |
| - | - |
| Cantidad | Hasta 16 |
| Formato | JPG / JPEG / PNG / WebP / HEIC / HEIF (no admite GIF) |
| Tamaño por imagen | Hasta 64 MB |
| Dimensiones por imagen | Cada lado entre 128 y 8192 píxeles; lado largo ÷ lado corto ≤ 4 |

> [!WARNING]
>
> Al usar URL, asegúrate de que el enlace sea **accesible públicamente**. Si no se puede acceder al enlace, la tarea fallará en la fase de generación (`status` será `failed` y se reembolsará el importe completo).
>
> En el modo de edición, la optimización del prompt está siempre activada y no se puede desactivar.

## Desactivar la optimización del prompt

De forma predeterminada, el modelo amplía el prompt antes de generar la imagen. Para generar siguiendo exactamente el texto original, envía `"prompt_optimizer": false`, siempre que:

* Se use solo para **texto a imagen**; con `image_urls` se devuelve 400
* Se **indique un tamaño explícito**: `size` debe ser una relación de aspecto (como `1:1`) o píxeles (como `1024x1024`), no `auto` ni omitido

Con la optimización desactivada, el modelo solo lee aproximadamente los primeros 4096 tokens del prompt.

## Response

**code** `integer`

Código de respuesta; 200 cuando el envío es correcto.

**data** `array`

Datos de la respuesta del envío.

**Elemento del array**

**status** `string`

Estado inicial: `submitted`.

**task\_id** `string`

Identificador único de la tarea, usado para consultar el estado y el resultado.

## Respuesta del envío

Tras un envío correcto, se devuelve de inmediato el ID de la tarea asíncrona:

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

## Consultar el resultado de la tarea

Usa el `task_id` de la respuesta del envío para llamar a la [API de consulta de tareas](https://docs.apimart.ai/es/api-reference/tasks/status.md):

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

La versión rápida genera imágenes más rápido que la estándar (en pruebas, la versión estándar tarda unos 10 a 20 segundos por imagen 1K / 2K y unos 20 segundos en 4K). Se recomienda consultar cada 3 a 5 segundos hasta que el estado cambie a `completed` o `failed`. Una tarea puede ejecutarse hasta 600 segundos; configura el timeout de sondeo del cliente en 10 minutos.

### Tarea completada

```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 ..."
          ]
        }
      ]
    }
  }
}
```

Las URL de las imágenes están en `data.result.images[0].url[]`, con las `n` imágenes en este único array. Descárgalas y guárdalas antes de `expires_at`. Si la tarea falla, `status` será `failed`, el motivo aparecerá en `error.message` y el importe se reembolsará íntegramente de forma automática.

## Ejemplos de uso

### Texto a imagen (4K predeterminado)

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

### Texto a imagen (1K + relación de aspecto, 4 imágenes)

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Foto de producto de unos auriculares en estilo minimalista, fondo blanco, sombras suaves",
  "size": "1:1",
  "resolution": "1K",
  "n": 4
}
```

### Píxeles exactos + PNG

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Cartel de una ciudad de noche, luces de neón, estilo cyberpunk, con el título NIGHT CITY",
  "size": "2048x1152",
  "output_format": "png"
}
```

### Edición con imágenes de referencia

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Ponle a la persona de la primera imagen la chaqueta de la segunda imagen, sin cambiar el fondo",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/jacket.png"
  ],
  "resolution": "2K"
}
```

### Desactivar la optimización del 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.