Saltar al contenido principal

Formato de Respuesta de Error

Cuando una tarea falla (status: "failed"), la respuesta incluye un objeto error:
{
  "id": "task-unified-1772618027-cmeisy8h",
  "object": "image.generation.task",
  "status": "failed",
  "model": "gemini-3.1-flash-image-preview",
  "progress": 0,
  "error": {
    "code": "content_policy_violation",
    "message": "Content policy violation.\nYour request was blocked by safety filters..."
  }
}
CampoTipoDescripcion
error.codestringIdentificador del codigo de error. Ver la lista completa a continuacion
error.messagestringDescripcion del error con consejos de solucion de problemas

Resumen de Codigos de Error

Errores del Cliente (Corregibles por el Usuario)

Codigo de ErrorDescripcionReintentable
content_policy_violationEl contenido viola las politicas de seguridadCorregir contenido, luego reintentar
invalid_parametersParametros de solicitud invalidosCorregir parametros, luego reintentar
image_processing_errorError en el procesamiento de imagenUsar otra imagen
image_dimension_mismatchLas dimensiones de la imagen no coinciden con la solicitudRedimensionar imagen, luego reintentar
request_cancelledLa solicitud fue canceladaReenviar
Codigo de ErrorDescripcionReintentable
generation_failed_no_contentEl modelo no pudo generar contenidoIntentar con otro prompt
service_errorError interno del servicioSe recupera automaticamente, reintentar mas tarde
generation_timeoutEl procesamiento de la tarea expiroReintentar mas tarde
resource_exhaustedRecursos upstream temporalmente agotadosSe recupera automaticamente, reintentar mas tarde
quota_exceededLimite de frecuencia o cuota excedidaReducir frecuencia, reintentar mas tarde
service_unavailableServicio temporalmente no disponibleSe recupera automaticamente, reintentar mas tarde
resource_not_foundID de tarea invalido o expiradoVerificar ID de tarea
unknown_errorError no clasificadoContactar soporte

Detalles de Codigos de Error

content_policy_violation

Violacion de Politica de Contenido

Su solicitud fue bloqueada por los filtros de seguridad. Este es el tipo de error mas comun, que cubre los siguientes escenarios:
Desencadenantes comunes:
SubtipoDescripcionMensaje de ejemplo
Personas fotorrealistasLa imagen subida contiene rostros humanos realesphotorealistic people detected
Semejanza con celebridadesInvolucra celebridades o figuras publicascelebrity detected in image
Derechos de autor/MarcasInvolucra logotipos de marcas, marcas registradas o PI con derechos de autorthird-party content violation
Adulto/NSFWContiene desnudez o contenido sexualmente sugerentenudity detected
Violencia/AutolesionContiene contenido violento, grafico o de autolesionviolence content blocked
Proteccion de menoresInvolucra contenido sensible relacionado con menoresminor content not allowed
Politica generalOtras violaciones de politica de contenidocontent policy violation
Como evitarlo:
  • Evite subir fotos reales de personas — use estilos de ilustracion o dibujos animados
  • Elimine logotipos de marcas, marcas registradas y personajes de PI con derechos de autor
  • Evite temas de adultos, violencia o autolesion
  • Use descripciones genericas de personajes (por ejemplo, “a person”) en lugar de referirse a celebridades especificas

generation_failed_no_content

Generacion Fallida

El modelo no pudo producir contenido para su solicitud. Aunque el formato de la solicitud era valido, el modelo no pudo generar un resultado durante el procesamiento.
Causas comunes:
  • Calidad deficiente del prompt: La descripcion es demasiado vaga o contradictoria para que el modelo la entienda
  • Limites de capacidad del modelo: El prompt excede las capacidades de generacion del modelo
  • Problemas del servicio upstream: El servicio del modelo subyacente devolvio un resultado vacio
  • Deteccion de contenido protegido: El prompt o la imagen de referencia puede involucrar eliminacion de marcas de agua o contenido protegido (logotipos, marcas registradas, etc.)
Como solucionarlo:
  • Ajuste su prompt para que sea mas claro y especifico
  • Use diferentes imagenes de referencia — evite imagenes con marcas de agua o logotipos
  • Simplifique la solicitud (menor resolucion o complejidad)
  • Simplemente reintente — algunos casos tienen exito al reintentar

invalid_parameters

Parametros Invalidos

Los parametros de la solicitud no cumplen con los requisitos del modelo.
Subtipos comunes:
SubtipoDescripcionEjemplo
Prompt demasiado largoEl prompt excede la longitud maxima del modeloPrompt is too long
Dimension de imagenEl ancho/alto o la relacion de aspecto de la imagen esta fuera de rangoimage dimensions must be between 240 and 7680
Archivo demasiado grandeEl archivo subido excede el limite de tamanofile size exceeds 10MB
Formato no soportadoEl formato del archivo subido no es compatibleunsupported file type
Duracion de videoLa duracion del video esta fuera del rango soportado por el modeloVideo duration must be between 1-30 seconds
Como solucionarlo:
  • Consulte la documentacion de la API especifica del modelo para los requisitos de parametros
  • Formatos de imagen soportados: JPG, PNG, WebP, GIF (HEIC, AVIF, TIFF no son soportados)
  • Limites de tamano de imagen: tipicamente < 10MB, algunos modelos < 30MB
  • Acorte su prompt o divida prompts largos en descripciones esenciales

image_processing_error

Error de Procesamiento de Imagen

El sistema no pudo procesar la imagen de entrada.
Causas comunes:
  • La URL de la imagen no es accesible (requiere autenticacion, restricciones de CDN, enlace expirado)
  • El formato de imagen no es compatible (por ejemplo, HEIC, AVIF)
  • El archivo de imagen esta danado
  • Problemas de red impidieron la descarga de la imagen
Como solucionarlo:
  • Asegurese de que la URL de la imagen sea accesible publicamente sin autenticacion ni restricciones de region
  • Use formatos estandar: JPG, PNG, WebP
  • Intente usar la API de carga de archivos en lugar de URLs
  • Verifique que la imagen se abra correctamente en un navegador

image_dimension_mismatch

Desajuste de Dimensiones de Imagen

Las dimensiones de la imagen de entrada no coinciden con las dimensiones especificadas en la solicitud. Comun en escenarios de imagen a video.
Ejemplo:
  • aspect_ratio=1280x720 (16:9) requiere una imagen horizontal de 1280x720
  • aspect_ratio=720x1280 (9:16) requiere una imagen vertical de 720x1280
Como solucionarlo: Redimensione su imagen para que coincida con el parametro aspect_ratio solicitado, o cambie el aspect_ratio para que coincida con su imagen.

service_error

Error de Servicio

Ocurrio un problema interno en el servicio upstream. Esto suele ser temporal — el sistema cambia automaticamente a otras rutas disponibles.
Causas comunes:
  • Servicio del modelo upstream temporalmente no disponible
  • Sobrecarga del servidor / alto trafico
  • Mantenimiento en curso
  • Conexion de red interrumpida
Como solucionarlo:
  • Espere 30-60 segundos y reintente — el sistema generalmente se recupera automaticamente
  • Si persiste, contacte al soporte tecnico
  • No necesita modificar su solicitud — reintente la misma solicitud

generation_timeout

Tiempo de Generacion Agotado

La tarea no se completo dentro del tiempo permitido.
Causas comunes:
  • Alta carga del sistema causando retrasos en la cola
  • Alta complejidad de la tarea (alta resolucion, video largo, etc.)
  • Respuesta lenta del servicio upstream
Como solucionarlo:
  • Reintente mas tarde, preferiblemente durante horas de menor demanda
  • Reduzca la complejidad de la tarea: menor resolucion, menor duracion del video
  • Simplifique las descripciones del prompt

quota_exceeded

Cuota / Limite de Frecuencia Excedida

Se han excedido los limites de frecuencia de solicitud o concurrencia.
Causas comunes:
  • Demasiadas solicitudes enviadas en un corto periodo (limitacion de frecuencia)
  • Multiples tareas procesandose simultaneamente (limite de concurrencia)
  • Cuota de la cuenta agotada
Como solucionarlo:
  • Reduzca la frecuencia de solicitudes — intervalo recomendado de 1-2 segundos entre solicitudes
  • Espere a que las tareas en curso se completen antes de enviar nuevas
  • Si la cuota esta agotada, visite la pagina de facturacion para recargar

resource_exhausted

Recursos Agotados

Los recursos de computo del servicio upstream estan temporalmente agotados. Generalmente ocurre durante periodos de uso pico del modelo.
Como solucionarlo:
  • Espere 1-5 minutos para la recuperacion automatica
  • El sistema cambia automaticamente entre multiples rutas — reintentar mas tarde generalmente tiene exito

resource_not_found

Recurso No Encontrado

El ID de tarea solicitado no existe o ha expirado.
Como solucionarlo:
  • Verifique que el ID de tarea este escrito correctamente
  • Los resultados de tareas tienen un periodo de expiracion — las tareas expiradas no se pueden consultar
  • Si el ID es correcto, reintente despues de una breve espera

request_cancelled

Solicitud Cancelada

La tarea fue cancelada o interrumpida durante el procesamiento.
Si no cancelo intencionalmente, simplemente reenvie la misma solicitud.

service_unavailable

Servicio No Disponible

Ocurrio un problema interno de autenticacion o conexion. Este error ha sido registrado automaticamente y tipicamente se resolvera rapidamente.
Como solucionarlo:
  • Espere unos minutos y reintente
  • Si persiste, contacte al soporte tecnico con su ID de tarea

unknown_error

Error Desconocido

Un error no clasificado. El sistema no pudo identificar el tipo de error especifico.
Como solucionarlo:
  • Reintente despues de una breve espera
  • Si el problema persiste, contacte al soporte tecnico con el ID de tarea completo

Mejores Practicas

Ejemplo de Manejo de Errores

import requests
import time

def poll_task_with_retry(task_id, api_key, max_retries=3):
    """Poll task status with automatic retry for server errors"""
    headers = {"Authorization": f"Bearer {api_key}"}

    for attempt in range(max_retries):
        resp = requests.get(
            f"https://api.evolink.ai/v1/tasks/{task_id}",
            headers=headers
        )
        data = resp.json()

        if data["status"] == "completed":
            return data["results"]

        if data["status"] == "failed":
            error = data.get("error", {})
            code = error.get("code", "unknown_error")
            message = error.get("message", "")

            # Client errors — not retryable, fix the request
            if code in [
                "content_policy_violation",
                "invalid_parameters",
                "image_processing_error",
                "image_dimension_mismatch",
            ]:
                raise Exception(f"Client error [{code}]: {message}")

            # Server errors — retryable
            if code in [
                "generation_failed_no_content",
                "service_error",
                "generation_timeout",
                "resource_exhausted",
                "quota_exceeded",
            ]:
                if attempt < max_retries - 1:
                    wait = 2 ** attempt * 5  # 5s, 10s, 20s
                    time.sleep(wait)
                    continue
                raise Exception(f"Server error [{code}]: {message}")

            raise Exception(f"Error [{code}]: {message}")

        # Task still processing
        time.sleep(3)

    raise Exception("Max polling attempts exceeded")

Reintentable vs No Reintentable

Corregir Solicitud Antes de Reintentar

  • content_policy_violation — Modificar contenido
  • invalid_parameters — Corregir parametros
  • image_processing_error — Usar otra imagen
  • image_dimension_mismatch — Redimensionar imagen

Seguro para Reintentar Directamente

  • generation_failed_no_content — Intentar con otro prompt
  • service_error — Esperar, luego reintentar
  • generation_timeout — Esperar, luego reintentar
  • resource_exhausted — Se recupera automaticamente
  • quota_exceeded — Reducir frecuencia, luego reintentar