Apariencia
Fallos de generación de imágenes
La generación de imágenes puede fallar incluso cuando el formato de la petición es válido. La mayoría de los fallos se deben a reglas de seguridad del proveedor, objetivos de prompt no compatibles, problemas con imágenes de referencia, capacidad temporal o límites de tasa. Pixapi mantiene alineados la respuesta de API, el estado de la tarea y el libro de créditos para que tu producto pueda mostrar el siguiente paso correcto.
Diagnóstico rápido
| Qué ves | Causa probable | Siguiente acción |
|---|---|---|
| Mensaje de seguridad o políticas | El prompt o la imagen de referencia activó controles de seguridad | Elimina contenido restringido, simplifica el prompt y reintenta con una descripción más segura. |
| Sin imagen o salida solo de texto | El modelo respondió sin una parte de imagen | Revisa las partes de respuesta, la modalidad solicitada, la complejidad del prompt y el soporte del modelo. |
Timeout, 503 o proveedor no disponible | Capacidad temporal del proveedor o problema de red | Reintenta con backoff limitado y conserva el mismo payload para una verificación. |
| Error de subida o imagen de referencia | Formato no compatible, archivo grande, dañado o URL inaccesible | Usa PNG, JPEG o WebP, reduce el tamaño y verifica que Pixapi pueda acceder a la URL. |
429 o límite de tasa | Presión de tasa a nivel de cuenta, modelo o proveedor | Usa backoff con jitter y encola trabajos no urgentes. |
insufficient_credits | El saldo era insuficiente antes de iniciar la generación | Pide al usuario que compre créditos; no es un caso de reembolso por fallo de generación. |
Causas comunes
Seguridad y contenido restringido
Los proveedores de imagen pueden bloquear prompts o imágenes de referencia con contenido sexual explícito, violencia gráfica, odio o acoso, autolesiones, actividades ilegales o contenido inapropiado relacionado con menores. Estas reglas pueden aplicarse durante la generación, no solo durante la validación inicial.
Eliminación de marcas de agua y material con copyright
Las solicitudes para eliminar marcas de agua, reproducir personajes protegidos, copiar IP famosa o imitar figuras públicas pueden rechazarse o no devolver una imagen útil. Replantea la petición como un concepto original, usa recursos licenciados o describe un estilo visual general.
Complejidad del prompt
Prompts muy largos, instrucciones contradictorias, requisitos densos de texto o demasiados sujetos pueden provocar salida solo de texto, salida parcial o ausencia de imagen. Reduce la petición al sujeto principal, estilo, composición y requisitos de salida antes de volver a añadir detalle.
Problemas con imágenes de referencia
Las solicitudes de edición e imagen-a-imagen dependen del recurso de entrada. Verifica que la URL sea accesible, que el archivo no esté dañado y que el formato sea compatible. Si una URL firmada expira rápido, vuelve a subir la imagen o usa una URL con mayor duración.
Problemas temporales del proveedor
La capacidad del proveedor, los límites de tasa y los timeouts upstream pueden aparecer de forma intermitente. En producción, reintenta pocas veces con backoff exponencial y jitter. Mantén el mismo modelo, payload e imagen de referencia para una primera repetición de diagnóstico.
Créditos reembolsados
Si los créditos se consumieron o reservaron, pero el trabajo de generación falla antes de entregar una salida facturable, Pixapi devuelve los créditos afectados a tu cuenta. El libro de créditos muestra esas filas como Reembolsado.
Abre Créditos para revisar las filas reembolsadas. Una fila reembolsada significa que el saldo fue restaurado; no significa que el prompt original vaya a funcionar sin cambios.
Qué registrar antes de contactar soporte
Incluye el request id o task id, modelo, hora, prompt sin datos sensibles, formato y tamaño de la imagen de entrada, código de error de respuesta y si los créditos fueron reembolsados. Esto ayuda a distinguir bloqueos de política, problemas de payload, caídas del proveedor y conciliación de facturación.