01
La semilla ayuda a comparar, pero no garantiza píxeles idénticos
Si el modelo acepta semilla, guárdala con el prompt, versión, tamaño y referencias. Algunos endpoints pueden dar otra imagen con la misma semilla.
Solución de API de imagen
Genera imágenes con los controles que el modelo expone de verdad.
Cada endpoint de imagen declara sus propios campos: unos aceptan indicación negativa, otros semilla, otros devuelven cuatro candidatas por llamada. Un formulario genérico esconde justo los controles que hacen reproducible un resultado.
El reto
Los formularios genéricos pierden los controles que importan
«Indicación dentro, imagen fuera» aguanta unos diez segundos. Después necesitas el mismo personaje una segunda vez, 3:2 en vez de cuadrado, cuatro candidatas por llamada y una semilla que puedas anotar.
02
El tamaño es un campo, no un preajuste
Unos endpoints aceptan resolution o aspect_ratio; otros, width y height en píxeles. Enviar el equivocado da 400, y donde se cobra por megapíxel el tamaño elegido es también el precio.
03
Una llamada puede devolver varias imágenes
Donde existe num_outputs, el cargo sigue al número de imágenes y no al de peticiones. Un valor por defecto de 4 cuesta cuatro veces uno de 1, y esa diferencia solo se ve antes del envío en la estimación.
El enfoque
Lee el esquema, conserva los campos, registra la semilla
Crea las entradas según el esquema del endpoint. Guarda la petición exacta, el orden de referencias y la versión con el resultado para comparar variantes. Conserva el original: no se garantiza regenerarlo idéntico.
Las tareas de imagen usan el mismo contrato de crear y seguir que el vídeo. Toda la diferencia vive dentro de input.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-image",
"input": {
"prompt": "A ceramic teapot on linen, soft window light, muted palette",
"aspect_ratio": "3:2",
"num_outputs": 2,
"seed": 1337
}
}GET /api/v1/jobs/recordInfo?taskId=…
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "succeeded",
"output": {
"assets": [
{
"mime": "image/png",
"url": "https://…/result.png?X-Amz-Signature=…",
"expiresAt": "2026-09-12T12:20:08Z"
}
]
},
"cost": "0.040000",
"settled": true
}
}Contrato
Lo que conviene fijar desde el principio
| Campo o cabecera | Valor o límite |
|---|---|
| input | additionalProperties: false |
| seed · num_outputs · aspect_ratio | declared per endpoint |
| cost + settled: false | hold · final charge never exceeds it |
| errorCode | 9 stable values, content_rejected included |
Desliza horizontalmente para ver todas las columnas.
Integración
De la primera llamada a producción
- 01Abre la página del modelo y mira cuáles de seed, negative_prompt, num_outputs y campos de tamaño están declarados.
- 02Construye el cuerpo desde input_schema; additionalProperties está cerrado, así que una clave no declarada es un 400 y no un silencio.
- 03Estima, envía con Idempotency-Key y guarda taskId, semilla y el valor model resuelto junto al resultado.
- 04Recoge output.assets desde la devolución o recordInfo y copia los archivos a tu propio bucket.
Encaje
Cuándo este camino es el adecuado
Elígelo si
- Generas a partir de texto y quieres varios creadores tras una sola forma de petición, un saldo y una factura.
- Quieres comparar variantes con una petición y versión del modelo guardadas.
Busca otra vía si
- Tus usuarios parten de una foto que ya tienen. La edición es otra tarea con su propio contrato de referencia.
- Quieres un estilo de casa único en todos los modelos. El estilo vive en el modelo, no en esta capa.
Comprobaciones
Lo que puedes verificar tú mismo
La petición de prueba es la de producción
El cuerpo que montas en la página del modelo es el que envía tu servidor: mismos campos, misma validación, misma estimación. No hay vista previa simplificada que luego diverja.
Los campos no declarados fallan con ruido
La entrada se valida contra el esquema del endpoint con additionalProperties cerrado. Un parámetro no declarado devuelve 400 con un errorCode estable en lugar de ignorarse.
Las salidas se sirven desde el almacenamiento de la plataforma
Los resultados llegan en output.assets con key, tipo MIME, url firmada y expiresAt. Nada enlaza al lugar donde se ejecutó el modelo.
Antes del lanzamiento
Comportamientos de la plataforma que conviene confirmar
- Decide antes del lanzamiento dónde se guardan las semillas; una semilla no guardada no sirve de nada.
- Fija el tope diario obligatorio en cada clave nueva y añade topes mensual y acumulado cuando corresponda.
- Trata el conjunto cerrado de errorCode, content_rejected incluido, como estados normales del producto.
- Replica los archivos a tu almacenamiento dentro de la ventana de conservación de 14 días.
Preguntas frecuentes
Lo que más se pregunta en esta página
Reutiliza las entradas, versión y semilla si existe. Esto no garantiza píxeles idénticos. Descarga y conserva la salida original cuando necesites esa imagen exacta.
En endpoints que declaran num_outputs, sí, y el cargo escala con el número. Estima el cuerpo para ver el importe del número que piensas enviar.
Los que declare el endpoint: resolution, aspect_ratio, o width y height. La página del modelo lista los valores admitidos y lo demás se rechaza antes de crear la tarea.
La plataforma no añade ninguno. El comportamiento viene del modelo elegido, y un rechazo llega como una tarea terminal normal con errorCode content_rejected.
Modelos
Modelos que puedes llamar para esto
Cada enlace abre la página de esa familia de modelos: entradas, límites, política de contenido y el precio actual por unidad.
ByteDanceSeedream 5.0 ProTexto a imagenPolítica de contenido: Sin censuraAlibabaQwen Image 2.1Edición de imagenPolítica de contenido: Sin censuraByteDanceSeedream 5.0 FlashTexto a imagenPolítica de contenido: Sin censuraAlibabaQwen Image Edit SpicyEdición de imagenPolítica de contenido: Sin censuraAlibabaZ-Image Spicy ProTexto a imagenPolítica de contenido: Sin censuraAlibabaQwen Image 3.0 ProEdición de imagenPolítica de contenido: Sin censura
Siguiente paso
Comparar endpoints de imagen en paralelo
Compara endpoints de imagen por entradas, controles de tamaño y semilla, número de salidas y precio por imagen, y reutiliza la petición probada.
Guías relacionadas