Guía para Desarrolladores de la API de Ketchup (Google Nano Banana 2)

Desarrolla rápido con tutoriales, ejemplos de datos y mejores prácticas diseñadas para los flujos de trabajo de imágenes de la API de Ketchup.

Ver Precios de la API de KetchupCompara los planes y niveles de uso de la API de Ketchup.

Resumen de la API de Ketchup

La API de Ketchup potencia fotos de productos, fondos de interfaces y gráficos sociales con calidad de renderizado predecible. El diseño REST mantiene las integraciones simples, mientras la plataforma escala desde creadores individuales hasta lanzamientos empresariales.

Capacidades de la API de Ketchup

Generación de texto a imagen optimizada para escenas de producción con modelos de la API de Ketchup.
Edición guiada por referencia con hasta cinco imágenes en una sola solicitud de la API de Ketchup.
Cola de trabajos asíncrona para que tu app se mantenga responsiva mientras la API de Ketchup renderiza.
Callbacks de webhook que permiten a la API de Ketchup enviar cambios de estado en tiempo real.
Esquemas JSON consistentes que mantienen las respuestas de la API de Ketchup fáciles de analizar.
Seguridad con token Bearer gestionada en el panel de la API de Ketchup.

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

Comenzando con la API de Ketchup

Abre un espacio de trabajo de la API de Ketchup y crea un token de acceso.
Agrega el token Bearer de la API de Ketchup al header Authorization para cada llamada.
Haz POST al endpoint de generación de imágenes de la API de Ketchup con prompts, modo y referencias.
Guarda el ID del trabajo devuelto y consulta el endpoint de estado o suscríbete a webhooks.
Descarga los archivos finales una vez que la API de Ketchup marque el trabajo como exitoso.

Autenticación

Cada solicitud de la API de Ketchup necesita un token Bearer válido. Rota las claves por entorno y audita el uso frecuentemente.

Método de Token Bearer

Adjunta tu token de la API de Ketchup al encabezado de Authorization como se muestra a continuación:

Authorization: Bearer <your-api-key>

Ejemplo de Formato de Token

Authorization: Bearer dk-1234567890abcdef

Solicitud de Muestra

curl -X POST "https://api.defapi.org/api/image/gen" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{
    "model": "google/gempix2",
    "prompt": "A beautiful landscape"
  }'

Lista de Verificación de Token Válido

✅ El token está activo y no ha expirado.
✅ El espacio de trabajo tiene acceso a la API de Ketchup habilitado.
✅ La cuenta tiene cuota restante o crédito.

Problemas Comunes

❌ Falta el encabezado de Authorization.
❌ Valor de token Bearer mal formado.
❌ Espacio de trabajo suspendido o token revocado.

Generación de Imágenes con API de Ketchup

Crea renders frescos, revisa assets existentes o mezcla mood boards con el endpoint de generación de la API de Ketchup.

Endpoint

POST /api/image/gen

Parámetros de Solicitud

Parameter	Type	Required	Description
model	string	Yes	Model identifier (e.g., "google/gempix2")
prompt	string	Yes	Text prompt describing the image
images	array	No	Reference image URLs (max 4)
callback_url	string	No	Webhook URL for completion notifications

Ejemplos de Código

Prompt Básico de API de Ketchup

{
  "model": "google/gempix2",
  "prompt": "A beautiful girl dancing in a garden"
}

Remix de API de Ketchup con Referencias

{
  "model": "google/gempix2",
  "prompt": "Put them in a basket",
  "images": [
    "https://cdn.openai.com/API/docs/images/body-lotion.png",
    "https://cdn.openai.com/API/docs/images/soap.png"
  ],
  "callback_url": "https://example.com/webhook/image-callback"
}

Esquema de Respuesta

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "ta12345678-1234-1234-1234-123456789abc"
  }
}

Manejo de Errores

400 - Bad Request

{"code": 1, "message": "failed", "detail": "prompt is required"}

401 - Unauthorized

{"code": 1, "message": "Invalid API key"}

Estado de Trabajo de API de Ketchup

Monitorea el progreso del renderizado y obtén URLs de entrega usando el endpoint de estado.

Endpoint

GET /api/task/query?task_id=<task_id>

Parámetros de Consulta

Parameter	Type	Required	Description
task_id	string	Yes	Unique task identifier returned from generation endpoint

Solicitud de Muestra

curl -X GET "https://api.defapi.org/api/task/query?task_id=ta823dfb-eaac-44fd-aec2-3e2c7ba8e071" \
  -H "Authorization: Bearer your-api-key-here"

Códigos de Estado

pending - La API de Ketchup aceptó la solicitud y puso el trabajo en cola.

submitted - La API de Ketchup programó el trabajo para procesamiento.

in_progress - La API de Ketchup está renderizando assets ahora.

success - La API de Ketchup terminó de renderizar y los assets están listos para descargar.

failed - La API de Ketchup no pudo renderizar el trabajo debido a un error.

Códigos de Error

404 - Task Not Found

{"code": 1, "message": "task not found"}

401 - Unauthorized

{"code": 401, "message": "Invalid API key"}

Modelos de Datos de la API Ketchup

Esquemas detallados para cargas de solicitud, respuestas de trabajos y cuerpos de webhooks utilizados en las integraciones de la API Ketchup.

ImageGenResult

Represents a generated image result.

{
  "image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
}

Field	Type	Description
image	string	Image URL or base64 data URI

CallbackPayload

Payload sent to the callback_url when task status changes to final states.

{
  "result": [
    {
      "image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
    }
  ],
  "status": "success",
  "task_id": "ta5c9705-b8ae-4cb9-aa6f-97c4fee88c8d",
  "consumed": "0.500000",
  "status_reason": {
    "message": null
  }
}

Field	Type	Description
result	array	Array of ImageGenResult objects (null if failed)
status	string	Final task status (success/failed)
task_id	string	Unique task identifier
consumed	string	Credits consumed by the task
status_reason	object	Status details including error message if failed

Esquemas de Modelos

google/gempix2Nano Banana image generation model

google/gemini-2.5-flash-imageGemini 2.5 Flash image model

Solución de Problemas

Comprende los formatos de error de la API Ketchup, reglas de reintento y cuándo escalar al soporte.

Códigos de Estado HTTP

200

OK

Request was successful

400

Bad Request

Invalid request parameters or malformed JSON

401

Unauthorized

Invalid, missing, or expired API key

404

Not Found

Task not found or endpoint doesn't exist

500

Internal Server Error

Server-side error occurred

Mejores Prácticas

Revisa el código de estado HTTP antes de analizar la carga.
Usa retroceso exponencial al reintentar trabajos de la API Ketchup después de errores 500.
Registra el ID de solicitud para que el equipo de soporte de la API Ketchup pueda rastrear problemas.
Valida prompts y URLs de imágenes localmente para evitar respuestas 400.
Rota los tokens de la API Ketchup si la autenticación comienza a fallar.
Consulta el estado del trabajo máximo una vez por segundo para respetar los límites de velocidad.
Prefiere webhooks para ejecuciones de alto volumen para que la API Ketchup pueda enviar actualizaciones.

Ejemplo de Manejo de Errores (JavaScript)

async function generateImage(prompt, apiKey) {
  try {
    const response = await fetch('https://api.defapi.org/api/image/gen', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        model: 'google/gempix2',
        prompt: prompt
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error ${response.status}: ${errorData.message}`);
    }

    const data = await response.json();
    return data.data.task_id;

  } catch (error) {
    console.error('Image generation failed:', error.message);
    throw error;
  }
}