Solución de API de edición
Los endpoints de edición toman al menos dos entradas: la imagen y la instrucción. Es en la imagen —URL pública, subida confirmada o data URI incrustada— donde se atascan la mayoría de las integraciones.
El reto
La indicación es la mitad fácil. La otra es un archivo en el teléfono de tus usuarios, que debe llegar al modelo sin exponer un bucket privado y cumplir límites que se comprueban antes de que exista la tarea.
01
Un campo de imagen declarado acepta una URL HTTPS pública, una URI de archivo spicy:// confirmada o una data URI incrustada. En línea: 1 MiB decodificado y 8.388.608 píxeles por imagen, dentro de un cuerpo de 2 MiB. Por encima hace falta un tique de subida.
02
Un enlace firmado puede apuntar a un bucket privado si nuestros servidores descargan el archivo sin cookies ni otro inicio de sesión. Debe seguir válido durante el procesamiento. Se rechazan IP privadas, loopback y credenciales user:password en la URL.
03
El nombre público de llamada termina en /edit, el esquema suele exigir image_url o image_urls y algunos endpoints añaden mask_url o strength. Un valor model de text-to-image dentro de un flujo de edición falla la validación en lugar de degradarse.
El enfoque
Para archivos de usuario pide un tique, envía por PUT exactamente los bytes declarados con todas las cabeceras devueltas, confirma y pasa la URI spicy:// en el campo de imagen del modelo. La referencia pasa a ser de tu cuenta, se comprueba una vez y se reutiliza sin volver a subirla.
Tique, PUT, confirmación, creación. El material ya público se salta los tres primeros pasos.
Ticket → PUT → commit → create
POST /api/v1/common/upload-url
{ "contentType": "image/png", "bytes": 482113 }
→ { "fileId": "fil_01k3…", "uploadUrl": "https://…", "method": "PUT", "headers": { … } }
PUT <uploadUrl> # exactly 482113 bytes, every returned header replayed
POST /api/v1/files/fil_01k3…/commit
→ { "status": "ready", "uri": "spicy://f/fil_01k3…", "sha256": "…" }POST /api/v1/jobs/createTask
{
"model": "<publisher>/<model>/edit",
"input": {
"prompt": "Replace the background with an overcast beach at dusk",
"image_urls": ["spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"]
}
}Contrato
| Campo o cabecera | Valor o límite |
|---|---|
| POST /api/v1/common/upload-url | JPEG · PNG · WebP · GIF ≤ 10 MiB |
| POST /api/v1/files/{fileId}/commit | returns spicy://f/fil_… |
| inline data URI | ≤ 1 MiB decoded · ≤ 8192 px per side |
| request body | ≤ 2 MiB · ≤ 16 images |
Desliza horizontalmente para ver todas las columnas.
Integración
Encaje
Comprobaciones
La confirmación compara bytes y tipo de medio con el tique, verifica la firma de la imagen y calcula un SHA-256. Solo entonces el archivo puede referenciarse.
Las data URI se guardan como archivos ligados a la cuenta. La entrada normalizada que devuelve recordInfo contiene URI de archivo, nunca los bytes Base64 originales.
El material subido se conserva un día; los resultados generados, 14 días. Ambos plazos están publicados y no se negocian por cuenta.
Antes del lanzamiento
Preguntas frecuentes
Modelos
Cada enlace abre la página de esa familia de modelos: entradas, límites, política de contenido y el precio actual por unidad.
Siguiente paso
Envía una imagen que ya tienes y una instrucción. Cómo entra la referencia, qué límites de píxeles rigen y por qué se cobra.
