> ## 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 con GPT-Image(1/1.5)

>  - Modo de procesamiento asíncrono, devuelve un ID de tarea para consultas posteriores
- Admite modos de generación texto a imagen, imagen a imagen e inpainting
- Admite fondos transparentes, múltiples formatos de salida y niveles de calidad
- Genera hasta 4 imágenes por solicitud, con hasta 15 imágenes de referencia 

<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": "gpt-image-1-official",
      "prompt": "An ancient castle under a starry sky",
      "size": "1:1",
      "quality": "auto",
      "n": 1
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "gpt-image-1-official",
      "prompt": "An ancient castle under a starry sky",
      "size": "1:1",
      "quality": "auto",
      "n": 1
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "gpt-image-1-official",
    prompt: "An ancient castle under a starry sky",
    size: "1:1",
    quality: "auto",
    n: 1,
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.apimart.ai/v1/images/generations"

      payload := map[string]interface{}{
          "model":   "gpt-image-1-official",
          "prompt":  "An ancient castle under a starry sky",
          "size":    "1:1",
          "quality": "auto",
          "n":       1,
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class Main {
      public static void main(String[] args) throws Exception {
          String url = "https://api.apimart.ai/v1/images/generations";

          String payload = """
          {
            "model": "gpt-image-1-official",
            "prompt": "An ancient castle under a starry sky",
            "size": "1:1",
            "quality": "auto",
            "n": 1
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer <token>")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.apimart.ai/v1/images/generations";

  $payload = [
      "model" => "gpt-image-1-official",
      "prompt" => "An ancient castle under a starry sky",
      "size" => "1:1",
      "quality" => "auto",
      "n" => 1
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  url = URI("https://api.apimart.ai/v1/images/generations")

  payload = {
    model: "gpt-image-1-official",
    prompt: "An ancient castle under a starry sky",
    size: "1:1",
    quality: "auto",
    n: 1
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = payload.to_json

  response = http.request(request)
  puts response.body
  ```

  ```swift Swift theme={null}
  import Foundation

  let url = URL(string: "https://api.apimart.ai/v1/images/generations")!

  let payload: [String: Any] = [
      "model": "gpt-image-1-official",
      "prompt": "An ancient castle under a starry sky",
      "size": "1:1",
      "quality": "auto",
      "n": 1
  ]

  var request = URLRequest(url: url)
  request.httpMethod = "POST"
  request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
  request.setValue("application/json", forHTTPHeaderField: "Content-Type")
  request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
      if let error = error {
          print("Error: \(error)")
          return
      }

      if let data = data, let responseString = String(data: data, encoding: .utf8) {
          print(responseString)
      }
  }

  task.resume()
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var url = "https://api.apimart.ai/v1/images/generations";

          var payload = @"{
              ""model"": ""gpt-image-1-official"",
              ""prompt"": ""An ancient castle under a starry sky"",
              ""size"": ""1:1"",
              ""quality"": ""auto"",
              ""n"": 1
          }";

          using var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");

          var content = new StringContent(payload, Encoding.UTF8, "application/json");
          var response = await client.PostAsync(url, content);
          var result = await response.Content.ReadAsStringAsync();

          Console.WriteLine(result);
      }
  }
  ```

  ```dart Dart theme={null}
  import 'dart:convert';
  import 'package:http/http.dart' as http;

  void main() async {
    final url = Uri.parse('https://api.apimart.ai/v1/images/generations');

    final payload = {
      'model': 'gpt-image-1-official',
      'prompt': 'An ancient castle under a starry sky',
      'size': '1:1',
      'quality': 'auto',
      'n': 1,
    };

    final response = await http.post(
      url,
      headers: {
        'Authorization': 'Bearer <token>',
        'Content-Type': 'application/json',
      },
      body: jsonEncode(payload),
    );

    print(response.body);
  }
  ```

  ```r R theme={null}
  library(httr)
  library(jsonlite)

  url <- "https://api.apimart.ai/v1/images/generations"

  payload <- list(
    model = "gpt-image-1-official",
    prompt = "An ancient castle under a starry sky",
    size = "1:1",
    quality = "auto",
    n = 1
  )

  response <- POST(
    url,
    add_headers(
      Authorization = "Bearer <token>",
      `Content-Type` = "application/json"
    ),
    body = toJSON(payload, auto_unbox = TRUE),
    encode = "raw"
  )

  cat(content(response, "text"))
  ```
</RequestExample>

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

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "Invalid request parameters",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient balance, please top up and try again",
      "type": "payment_required"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "Access forbidden, you do not have permission to access this resource",
      "type": "permission_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests, please try again later",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": 500,
      "message": "Internal server error, please try again later",
      "type": "server_error"
    }
  }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": 502,
      "message": "Bad gateway, server temporarily unavailable",
      "type": "bad_gateway"
    }
  }
  ```
</ResponseExample>

## Modelos compatibles

| Modelo                   | Descripción                                                              | Modos                            | Imagen a imagen | Imágenes máx. | Facturación    |
| ------------------------ | ------------------------------------------------------------------------ | -------------------------------- | --------------- | ------------- | -------------- |
| `gpt-image-1-official`   | Estabilidad prioritaria, adecuado para generación de imágenes en general | Texto a imagen / Imagen a imagen | Compatible      | 4             | Size x Quality |
| `gpt-image-1.5-official` | Versión nueva, adecuada para mayor calidad y edición compleja            | Texto a imagen / Imagen a imagen | Compatible      | 4             | Size x Quality |

## Autorizaciones

<ParamField header="Authorization" type="string" required>
  Todas las solicitudes a la API requieren autenticación con Bearer Token

  Obtenga su API Key:

  Visite la [página de gestión de API Keys](https://apimart.ai/keys) para obtener su API Key

  Añada lo siguiente a los encabezados de la solicitud:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Nombre del modelo

  * `gpt-image-1-official` - Estabilidad prioritaria, adecuado para generación de imágenes en general
  * `gpt-image-1.5-official` - Versión nueva, adecuada para mayor calidad y edición compleja
</ParamField>

<ParamField body="prompt" type="string" required>
  Descripción textual para la generación de la imagen, admite chino e inglés
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Proporción de la imagen

  Proporciones compatibles:

  * `1:1` - Cuadrada (predeterminado)
  * `3:2` - Horizontal
  * `2:3` - Vertical
</ParamField>

<ParamField body="n" type="integer" default="1">
  Número de imágenes a generar

  Rango: 1-4

  * Los valores ≤ 0 se tratarán como `1`
  * Los valores > 4 se tratarán como `4`

  **Advertencia:** Debe ser un número puro (p. ej. `1`), no añada comillas o se producirá un error
</ParamField>

<ParamField body="quality" type="string" default="auto">
  Calidad de la imagen

  * `auto` - Selección automática de la calidad (predeterminado)
  * `low` - Más rápido y económico
  * `medium` - Equilibrio entre calidad y coste
  * `high` - Mayor calidad, mayor coste
</ParamField>

<ParamField body="background" type="string" default="auto">
  Modo de fondo

  * `auto` - Fondo automático (predeterminado)
  * `opaque` - Fondo opaco
  * `transparent` - Fondo transparente, recomendado junto con el formato de salida `png`

  <Warning>
    `background: transparent` no puede usarse simultáneamente con `output_format: jpeg`
  </Warning>
</ParamField>

<ParamField body="moderation" type="string" default="auto">
  Nivel de moderación

  * `auto` - Nivel de moderación predeterminado
  * `low` - Moderación más permisiva
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Formato de salida

  * `png` - Formato predeterminado, adecuado para fondos transparentes
  * `jpeg` - Tamaño de archivo menor, adecuado para salida de imágenes en general

  <Warning>
    `background: transparent` no puede usarse simultáneamente con `output_format: jpeg`
  </Warning>
</ParamField>

<ParamField body="output_compression" type="integer">
  Nivel de compresión de salida, rango 0-100

  * Recomendado solo para `jpeg`
  * No recomendado para `png`
</ParamField>

<ParamField body="image_urls" type="array">
  Array de URLs de imágenes de referencia; activa el modo imagen a imagen cuando se proporciona

  <Expandable title="Detalles">
    * 1 imagen para edición con referencia única
    * 2-15 imágenes para edición con fusión multireferencia
    * Más de 15 imágenes serán rechazadas
    * Deben ser URLs de imagen estables y accesibles públicamente
  </Expandable>

  **Límite:** Hasta 15 imágenes de referencia
</ParamField>

<ParamField body="mask_url" type="string">
  URL de la imagen de máscara para inpainting

  * Debe usarse junto con `image_urls`
  * Se enviará a través de la API oficial de edición

  <Warning>
    1. Antes de cargar la imagen de máscara, confirme que el canal Alpha de la imagen sea "Sí".

    2. El tamaño de la imagen de máscara debe coincidir con el de la primera imagen de referencia.
  </Warning>
</ParamField>

## Referencia de tamaños

Las proporciones se utilizan externamente; el sistema las mapea automáticamente a las dimensiones oficiales internamente.

| Proporción | Tamaño real | Descripción |
| ---------- | ----------- | ----------- |
| `1:1`      | 1024x1024   | Cuadrada    |
| `2:3`      | 1024x1536   | Vertical    |
| `3:2`      | 1536x1024   | Horizontal  |

## Ejemplos de uso

**Texto a imagen (mínimo)**

```json theme={null}
{
  "model": "gpt-image-1-official",
  "prompt": "An ancient castle under a starry sky"
}
```

**Texto a imagen (parámetros completos)**

```json theme={null}
{
  "model": "gpt-image-1-official",
  "prompt": "A flat icon of a glass bottle with no background",
  "size": "2:3",
  "quality": "high",
  "background": "transparent",
  "moderation": "low",
  "output_format": "png",
  "n": 1
}
```

**Imagen a imagen (referencia única)**

```json theme={null}
{
  "model": "gpt-image-1.5-official",
  "prompt": "Convert the reference image to illustration style, preserving the main outline",
  "size": "1:1",
  "quality": "auto",
  "image_urls": [
    "https://your-cdn.com/input.png"
  ],
  "n": 1
}
```

**Imagen a imagen (fusión multireferencia)**

```json theme={null}
{
  "model": "gpt-image-1.5-official",
  "prompt": "Merge two reference images into an illustration poster, preserving the main outlines",
  "size": "1:1",
  "quality": "auto",
  "background": "transparent",
  "image_urls": [
    "https://your-cdn.com/input-a.png",
    "https://your-cdn.com/input-b.png"
  ],
  "moderation": "low",
  "output_format": "png",
  "n": 1
}
```

**Múltiples imágenes (n > 1)**

```json theme={null}
{
  "model": "gpt-image-1-official",
  "prompt": "Four minimalist poster variations of a red fox",
  "size": "1:1",
  "quality": "low",
  "output_format": "png",
  "n": 4
}
```

## Response

<ResponseField name="code" type="integer">
  Código de estado de la respuesta
</ResponseField>

<ResponseField name="data" type="array">
  Array de datos de la respuesta

  <Expandable title="Propiedades">
    <ResponseField name="status" type="string">
      Estado de la tarea

      * `submitted` - Enviada
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador único de la tarea
    </ResponseField>
  </Expandable>
</ResponseField>

## Notas

1. **Procesamiento asíncrono**: Tras el envío se devuelve un `task_id`. Haga polling en `/v1/tasks/{task_id}` para obtener los resultados
2. **Selección de modelo**: Use `gpt-image-1-official` para generación de imágenes general; use `gpt-image-1.5-official` para edición de alta calidad y tareas complejas de imagen a imagen
3. **Requisitos de la URL de la imagen**: Para imagen a imagen, use URLs de imagen estables y accesibles públicamente
4. **Facturación**: Se cobra por cada imagen generada con éxito; sin cargo en caso de fallo