Imágenes de referencia

01Cómo pasar una imagen de referencia

Las imágenes de referencia son opcionales: sin ellas, el modelo dibuja solo a partir del texto. Si las necesitas, elige una familia de campos: un archivo que hayas subido de antemano o la dirección de una imagen.

{
  "model": "nano-banana-pro",
  "prompt": "Conserva la lámpara y colócala en un alféizar claro",
  "resolution": "2K",
  "image_file_ids": ["ea7b3c89972d3657"]
}

{
  "model": "nano-banana-pro",
  "prompt": "Conserva la lámpara y colócala en un alféizar claro",
  "resolution": "2K",
  "image_urls": ["https://cdn.example.com/products/lamp.png"]
}

02Carga de un archivo

Envía el archivo como multipart/form-data: el campo file es el archivo en sí, y el campo kind lleva el valor image. La respuesta trae file_id: ese es el valor que debes poner en la solicitud de generación.

curl --fail-with-body --connect-timeout 10 --max-time 120 \
  -X POST https://api.rendergrid.io/api/public/v1/uploads \
  -H "Authorization: Bearer $RENDERGRID_API_KEY" \
  -F "file=@lamp.png;type=image/png" \
  -F "kind=image"

import os
import requests

key = os.environ["RENDERGRID_API_KEY"]
with open("lamp.png", "rb") as image:
    response = requests.post(
        "https://api.rendergrid.io/api/public/v1/uploads",
        headers={"Authorization": f"Bearer {key}"},
        files={"file": ("lamp.png", image, "image/png")},
        data={"kind": "image"},
        timeout=(10, 120),
    )
response.raise_for_status()
upload = response.json()
print(upload["file_id"], upload["expires_at"])

// Node.js 22+, archivo .mjs
import { readFile } from "node:fs/promises";

const bytes = await readFile("lamp.png");
const file = new Blob([bytes], { type: "image/png" });
const form = new FormData();
form.append("file", file, "lamp.png");
form.append("kind", "image");

const API = "https://api.rendergrid.io/api/public/v1";
const key = process.env.RENDERGRID_API_KEY;
const response = await fetch(`${API}/uploads`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}` },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) {
  const body = await response.text();
  throw new Error(`HTTP ${response.status}: ${body}`);
}
const upload = await response.json();
console.log(upload.file_id, upload.expires_at);

{
  "file_id": "ea7b3c89972d3657",
  "url": "https://cdn.rendergrid.io/user_uploads/example.png",
  "expires_at": "2026-10-14T12:00:00+00:00"
}

file_id

El identificador del archivo. Pertenece a la cuenta que lo subió.

url

La dirección de la copia del archivo. No es un almacenamiento permanente: después de expires_at no se puede usar.

expires_at

Cuándo file_id deja de funcionar: 24 horas después de la carga.

Comprueba el archivo antes de enviarlo

Así responderá la API a los archivos más habituales. Todos los rechazos llegan al instante, antes de la generación.

03Dirección en lugar de archivo

Si la imagen ya está en internet, no la subas: pasa el enlace en image_urls. La imagen la descarga nuestro servidor, así que el enlace debe abrirse desde fuera sin iniciar sesión.

• Una dirección pública http:// o https:// en el puerto 80 o 443. No sirven las direcciones de redes internas ni los enlaces con usuario y contraseña incluidos.
• No se siguen las redirecciones: indica la dirección final de la imagen.
• La respuesta debe ser una imagen PNG, JPEG o WebP de no más de 25 MiB.
• La fuente debe responder rápido: el tiempo de descarga está limitado. Si la fuente es lenta o está protegida con contraseña, descarga el archivo por tu parte y súbelo con POST /uploads.

04Cómo preparar las imágenes de referencia

• Describe en prompt qué conservar y qué cambiar. El modelo ve la imagen de referencia, pero no sabe qué quieres hacer con ella.
• En una solicitud caben hasta 14 imágenes de referencia.
• Una imagen de referencia de más de 7 MiB o de más de 4 096 píxeles en el lado largo puede reducirse o comprimirse antes de trabajar con ella. En las imágenes grandes con fondo transparente, el fondo puede volverse blanco.
• Guarda los originales por tu parte: file_id vale 24 horas desde la carga, y el archivo en sí se elimina 48 horas después de la última carga.
• Las máscaras (inpainting) no se admiten. Envía la imagen original como imagen de referencia y describe la edición con palabras.

05Qué puede salir mal

Estos rechazos llegan antes del cargo: el saldo no cambia.

Si la imagen de referencia deja de estar disponible ya después de aceptar la solicitud, la tarea termina con el estado failed y failure.code: reference_unavailable o reference_fetch_failed. Más información en «Códigos de error».

FAQPreguntas frecuentes