Saltar al contenido principal

Descripción general

Crea una imagen editada o extendida dada una imagen original y un prompt. El endpoint admite ambos flujos:
  • el flujo de carga multipart/form-data compatible con OpenAI documentado abajo
  • solicitudes JSON que proporcionan image_url, image_urls o referencias oficiales images para familias de imagen a imagen compatibles
gpt-image-2 es compatible aquí. Acepta uploads multipart image, JSON image_url / image_urls y referencias oficiales images[] (image_url o file_id), hasta 16 imágenes fuente. Crea los file_id primero con /v1/files. Usa async: true para recibir una tarea primero; los modelos de edición oficiales FLUX/BFL usan el mismo flujo de polling.Las ediciones con gpt-image-2 no aceptan resolution ni background; usa size para las dimensiones de salida. Para ediciones con varias imágenes o alta latencia, prefiere async: true y consulta la tarea devuelta.Las solicitudes Nano Banana con imagen de referencia (nano-banana, nano-banana-2 y nano-banana-pro) se exponen en /v1/images/generations con operation: "image-to-image" e image_urls, no en este endpoint /v1/images/edits.Los modelos de edición de imagen xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality y el legacy grok-imagine-image-pro) aceptan como máximo 3 imágenes fuente. Las solicitudes con más de 3 imágenes fuente fallan durante la validación de entrada con 400 too_many_images.input_fidelity no forma parte del campos admitidos actual de TokenLab para gpt-image-2; omítelo o la solicitud devolverá 400 unsupported_parameter.

Cuerpo de la solicitud

Tiempo de espera de solicitudes síncronas: algunas solicitudes de imagen devuelven la imagen final inline y esperan a que termine la generación. Las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más, así que configura el timeout de tu cliente HTTP en al menos 120s. Si la respuesta de creación incluye status: "pending", task_id o poll_url, sigue el poll_url devuelto en su lugar. URLs de imagen remotas: cuando se necesita entrada multipart, TokenLab descarga JSON image_url, image_urls o images[].image_url y envía los bytes como partes multipart image. Las URLs deben ser públicas http/https, sin credenciales incrustadas ni fragmentos, y no deben resolver a localhost ni a rangos IP privados o reservados; cada redirección se valida de nuevo. El contenido descargado debe ser una imagen PNG, JPEG o WebP real. Límites: 50MB por imagen, 200MB en total para imágenes descargadas por URL en una solicitud, timeout de 10s y hasta 3 redirecciones.
image
file
Imágenes fuente multipart. Repite image para enviar varias fuentes de GPT Image. Los archivos deben ser PNG, JPEG o WebP, hasta 16 imágenes fuente y 50MB cada una. Los modelos de edición xAI Grok Imagine usan los mismos campos de entrada, pero limitan las imágenes fuente a 3.
prompt
string
requerido
Una descripción de texto de la edición deseada.
mask
file
Una imagen adicional cuyas áreas completamente transparentes indican dónde se debe editar la imagen. Debe ser un archivo PNG válido, menor de 50MB y tener las mismas dimensiones que image.En solicitudes JSON, mask también puede ser un objeto con exactamente uno de image_url o file_id; los valores file_id deben venir de /v1/files y permanecer vinculados a la misma configuración de edición de imagen.
model
string
requerido
Modelo que se usará para editar imágenes. Usa gpt-image-2 para ediciones GPT Image, u otro modelo actual de edición de imágenes devuelto por GET /v1/models?recommended_for=image.
n
integer
predeterminado:"1"
El número de imágenes a generar. Debe estar entre 1 y 10.
size
string
Tamaño de la imagen generada. Para gpt-image-2, usa auto o WIDTHxHEIGHT; las dimensiones deben ser múltiplos de 16, el lado más largo como máximo 3840px, la relación lado largo/corto como máximo 3:1, y el total de píxeles entre 655,360 y 8,294,400.
response_format
string
predeterminado:"url"
Formato en el que se devuelven las imágenes generadas. Debe ser url o b64_json; el valor predeterminado es url.Para solicitudes gpt-image-2 de Azure Official o compatibles con Azure, TokenLab recibe los datos de imagen como b64_json. Para solicitudes url, TokenLab sube cada imagen al CDN y devuelve data[].url. Si el almacenamiento CDN no está disponible o la subida falla, la solicitud falla en lugar de convertirse en una respuesta Base64. Para b64_json, devuelve el Base64 sin procesar.
async
boolean
predeterminado:"false"
Establécelo en true con gpt-image-2 o modelos de edición oficiales FLUX/BFL para devolver una tarea antes de que la imagen final esté lista. Las ediciones asíncronas completadas devuelven URL sin importar el response_format solicitado; usa solicitudes síncronas si necesitas b64_json.
user
string
Un identificador único que representa a su usuario final para monitoreo de abuso.

Respuesta

created
integer
Marca de tiempo Unix de cuando se crearon las imágenes.
data
array
Array de imágenes generadas.Cada objeto contiene:
  • url (string): URL de la imagen editada (si response_format es url)
  • b64_json (string): Imagen codificada en Base64 (si response_format es b64_json)

Respuesta de tarea asíncrona

Usa async: true con gpt-image-2 o modelos de edición oficiales FLUX/BFL para crear una tarea en lugar de esperar la imagen editada en la solicitud. La respuesta incluye status: "pending", task_id y poll_url. Consulta /v1/tasks/{task_id} hasta que la tarea llegue a completed o failed. Las tareas asíncronas de edición solo devuelven las URL finales. Si necesitas datos de imagen b64_json sin procesar, usa una solicitud síncrona. Al crear la tarea puede reservarse el importe estimado. Las tareas completadas se cobran por uso real; las fallidas o vencidas liberan o reembolsan la reserva.
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.images.edit(
    model="gpt-image-2",
    image=open("sunlit_lounge.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="A sunlit indoor lounge area with a pool",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)
import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.images.edit({
  model: 'gpt-image-2',
  image: fs.createReadStream('sunlit_lounge.png'),
  mask: fs.createReadStream('mask.png'),
  prompt: 'A sunlit indoor lounge area with a pool',
  n: 1,
  size: '1024x1024'
});

console.log(response.data[0].url);
package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func main() {
    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)

    writer.WriteField("model", "gpt-image-2")

    image, _ := os.Open("sunlit_lounge.png")
    defer image.Close()
    part, _ := writer.CreateFormFile("image", "sunlit_lounge.png")
    io.Copy(part, image)

    mask, _ := os.Open("mask.png")
    defer mask.Close()
    maskPart, _ := writer.CreateFormFile("mask", "mask.png")
    io.Copy(maskPart, mask)

    writer.WriteField("prompt", "A sunlit indoor lounge area with a pool")
    writer.WriteField("n", "1")
    writer.WriteField("size", "1024x1024")
    writer.Close()

    req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/images/edits", body)
    req.Header.Set("Authorization", "Bearer sk-your-api-key")
    req.Header.Set("Content-Type", writer.FormDataContentType())

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    result, _ := io.ReadAll(resp.Body)
    fmt.Println(string(result))
}
<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/edits');

$image = new CURLFile('sunlit_lounge.png', 'image/png', 'sunlit_lounge.png');
$mask = new CURLFile('mask.png', 'image/png', 'mask.png');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => [
        'model' => 'gpt-image-2',
        'image' => $image,
        'mask' => $mask,
        'prompt' => 'A sunlit indoor lounge area with a pool',
        'n' => 1,
        'size' => '1024x1024'
    ]
]);

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

$data = json_decode($response, true);
echo $data['data'][0]['url'];
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Notas

Los fallos al descargar imágenes remotas se devuelven como errores de entrada antes de que comience la generación. URLs inaccesibles, timeouts, respuestas 403/404, hosts privados/internos, credenciales o fragmentos en la URL, contenido que no es imagen, formatos no compatibles y excesos de tamaño devuelven 400 o 413 e identifican image_url / image_urls[n]. Para recursos privados o protegidos por headers, sube archivos multipart image directamente o crea referencias /v1/files.