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

# Hy-Image-3.5 Preview Generación de imágenes

> Texto a imagen, hasta 5 imágenes de referencia, salida 1K / 2K / 4K o dimensiones exactas. Una imagen por solicitud.

<Info>
  Este endpoint es asíncrono. Tras enviar, obtén el ID en `data[0].task_id` y usa [Consulta de tareas](/es/api-reference/tasks/status) para ver el estado y la imagen. Consulta cada 3–5 segundos; se recomienda un tiempo de espera total del cliente de 5 minutos. Detente en `completed` o `failed`.
</Info>

<RequestExample>
  ```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": "hy-image-v3.5-preview",
      "prompt": "A golden retriever running on a beach in warm evening light",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

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

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "hy-image-v3.5-preview",
          "prompt": "A golden retriever running on a beach in warm evening light",
          "size": "16:9",
          "resolution": "2K"
      }
  )
  response.raise_for_status()
  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: "hy-image-v3.5-preview",
      prompt: "A golden retriever running on a beach in warm evening light",
      size: "16:9",
      resolution: "2K"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Cabeceras de solicitud

<ParamField header="Authorization" type="string" required>
  Autenticación Bearer: `Bearer <token>`, donde `<token>` es tu APIMart API Key.
</ParamField>

## Parámetros de solicitud

<ParamField body="model" type="string" required>
  Valor fijo: `hy-image-v3.5-preview`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Descripción para generar o editar imágenes. Admite chino e inglés; no puede estar vacía.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Relación de aspecto o dimensiones exactas en píxeles.

  * Relación: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
  * Píxeles exactos: por ejemplo `2000x1104`, sujeto a los límites indicados abajo.
  * `auto` u omitido: el modelo elige la relación según el prompt.

  Con píxeles exactos, `resolution` no determina las dimensiones.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Nivel de resolución: `1K`, `2K` o `4K`; por defecto `1K`.

  Con píxeles exactos, este campo no determina el tamaño. Usa siempre un valor admitido; los demás devuelven HTTP 400.
</ParamField>

<ParamField body="width" type="integer">
  Anchura exacta en píxeles. Debe enviarse con `height` y tiene prioridad sobre `size` y `resolution`.

  Anchura de 256 a 8192; anchura × altura no debe superar 8.294.400. Se recomiendan múltiplos de 16.
</ParamField>

<ParamField body="height" type="integer">
  Altura exacta en píxeles. Debe enviarse con `width`.

  Altura de 256 a 8192; anchura × altura no debe superar 8.294.400. Se recomiendan múltiplos de 16.
</ParamField>

<ParamField body="image_urls" type="string[]">
  URL públicas de referencia, hasta 5 imágenes. Omitir para texto a imagen; incluir para generación con referencias mediante el mismo endpoint.

  Admite JPEG, PNG y WEBP. Se recomienda menos de 7MB por imagen. Las URL deben ser públicas.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Contenido que no debe aparecer en la imagen.
</ParamField>

<ParamField body="seed" type="integer">
  Semilla aleatoria; entero no negativo. `0` u omisión usa un valor aleatorio.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Una imagen por solicitud. Solo se admite `1`; otros valores devuelven HTTP 400.
</ParamField>

## Selección de dimensiones

Prioridad: par `width` / `height` → píxeles exactos en `size` → relación o `auto` en `size` junto con `resolution`.

Para píxeles exactos, anchura y altura deben estar entre 256 y 8192, con un máximo total de 8.294.400 píxeles. Se recomiendan múltiplos de 16 para ambas.

### Ejemplo de píxeles exactos

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}
```

También puedes omitir `width` y `height` y enviar `"size": "2000x1104"`.

### Ejemplo con imagen de referencia

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "Make the car in the reference image red, preserving the original background and lighting",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "blur, text watermarks",
  "seed": 42,
  "n": 1
}
```

Sustituye las URL de ejemplo por direcciones públicas reales. Para varias referencias, añade URL a `image_urls`, hasta 5 imágenes en total.

## Respuesta de envío

<ResponseField name="code" type="integer">
  Código de respuesta; `200` indica éxito.
</ResponseField>

<ResponseField name="data" type="array">
  Resultado del envío de la tarea.

  <Expandable title="Mostrar campos de tarea">
    <ResponseField name="status" type="string">
      `submitted` indica envío correcto, no que la imagen esté generada.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID de tarea para consultar estado y resultados.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consultar resultados

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

Ejemplo de respuesta correcta (URL de imagen de ejemplo):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}
```

* `pending` / `processing`: seguir consultando.
* `completed`: obtener la URL de `data.result.images[0].url[0]`; `url` es un array de cadenas.
* `failed`: detener consultas y leer la causa en `data.error.message`. Reembolso íntegro. Los prompts que infringen las normas y los rechazos de moderación también se tratan como fallos.

Las imágenes se almacenan en el CDN de la plataforma. Descárgalas antes de la fecha `expires_at` indicada en el resultado.

## Facturación

Se factura por imagen. Consulta los [precios de modelos](https://apimart.ai/pricing).

* Con una relación de aspecto, se cobra según el nivel `resolution`.
* Con píxeles exactos, el lado más corto determina el nivel:

| Nivel | Lado más corto |
| - | - |
| 1K | Hasta 1024 píxeles |
| 2K | 1025–2048 píxeles |
| 4K | Más de 2048 píxeles |

Las tareas fallidas reciben un reembolso íntegro.

## Errores de parámetros frecuentes

Los siguientes casos devuelven HTTP 400 de forma síncrona, sin crear tarea ni cobrar:

| Problema | Acción |
| - | - |
| `prompt` vacío | Proporcionar un prompt no vacío |
| `n` distinto de `1` | Solicitar solo una imagen cada vez |
| `seed` negativo | Usar un entero no negativo; `0` significa aleatorio |
| `resolution` no admitida | Usar `1K`, `2K` o `4K` |
| Relación de `size` no admitida | Usar una de las 10 relaciones indicadas o `auto` |
| Dimensiones fuera de rango | Anchura y altura entre 256 y 8192, total máximo de 8.294.400 píxeles |
| Más de 5 imágenes de referencia | Reducir `image_urls` a un máximo de 5 imágenes |


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