Guida per Sviluppatori Ketchup API (Google Nano Banana 2)

Sviluppa velocemente con tutorial, payload di esempio e best practice pensate per i flussi di lavoro delle immagini di Ketchup API.

Vedi i Prezzi di Ketchup APIConfronta i piani e i livelli di utilizzo di Ketchup API.

Panoramica Ketchup API

Ketchup API alimenta foto di prodotti, sfondi UI e grafiche social con qualità di rendering prevedibile. Il design REST mantiene le integrazioni semplici, mentre la piattaforma scala da creatori singoli a lanci aziendali.

Capacità di Ketchup API

Generazione da testo a immagine ottimizzata per scene di produzione con i modelli Ketchup API.
Editing guidato da riferimento con fino a cinque immagini in una singola richiesta Ketchup API.
Coda di lavori asincrona così la tua app rimane reattiva mentre Ketchup API renderizza.
Callback webhook che permettono a Ketchup API di inviare cambiamenti di stato in tempo reale.
Schemi JSON consistenti che mantengono le risposte Ketchup API facili da analizzare.
Sicurezza con token Bearer gestita nella dashboard Ketchup API.

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

Iniziare con Ketchup API

Apri un workspace Ketchup API e crea un token di accesso.
Aggiungi il token Bearer Ketchup API all'header Authorization per ogni chiamata.
Fai POST all'endpoint di generazione immagini Ketchup API con prompt, modalità e riferimenti.
Memorizza l'ID lavoro restituito e interroga l'endpoint di stato o iscriviti ai webhook.
Scarica i file finali una volta che Ketchup API contrassegna il lavoro come successo.

Autenticazione

Ogni richiesta API Ketchup richiede un token Bearer valido. Ruota le chiavi per ambiente e controlla l'utilizzo spesso.

Metodo Token Bearer

Allega il tuo token API Ketchup all'header Authorization come mostrato sotto:

Authorization: Bearer <your-api-key>

Esempio Formato Token

Authorization: Bearer dk-1234567890abcdef

Richiesta di Esempio

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 di Controllo Token Valido

✅ Il token è attivo e non scaduto.
✅ Il workspace ha l'accesso API Ketchup abilitato.
✅ L'account ha quota rimanente o credito.

Problemi Comuni

❌ Header Authorization mancante.
❌ Valore token Bearer malformato.
❌ Workspace sospeso o token revocato.

Generazione Immagini API Ketchup

Crea nuovi render, rivedi asset esistenti, o mixa mood board con l'endpoint di generazione API Ketchup.

Endpoint

POST /api/image/gen

Parametri Richiesta

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

Esempi di Codice

Prompt Base API Ketchup

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

Remix API Ketchup con Riferimenti

{
  "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"
}

Schema Risposta

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

Gestione Errori

400 - Bad Request

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

401 - Unauthorized

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

Stato Lavoro API Ketchup

Monitora il progresso del rendering e ottieni gli URL di consegna usando l'endpoint di stato.

Endpoint

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

Parametri Query

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

Richiesta di Esempio

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

Codici di Stato

pending - L'API Ketchup ha accettato la richiesta e messo in coda il lavoro.

submitted - L'API Ketchup ha programmato il lavoro per l'elaborazione.

in_progress - L'API Ketchup sta renderizzando gli asset ora.

success - L'API Ketchup ha finito il rendering e gli asset sono pronti per il download.

failed - L'API Ketchup non è riuscita a renderizzare il lavoro a causa di un errore.

Codici di Errore

404 - Task Not Found

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

401 - Unauthorized

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

Modelli di Dati API Ketchup

Schemi dettagliati per payload di richiesta, risposte di lavoro e corpi webhook utilizzati nelle integrazioni 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

Schemi dei Modelli

google/gempix2Nano Banana image generation model

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

Risoluzione dei Problemi

Comprendi i formati di errore dell'API Ketchup, le regole di ripetizione e quando escalare al supporto.

Codici di Stato 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

Migliori Pratiche

Controlla il codice di stato HTTP prima di analizzare il payload.
Usa il backoff esponenziale quando riprovi i lavori dell'API Ketchup dopo errori 500.
Registra l'ID della richiesta così il team di supporto dell'API Ketchup può tracciare i problemi.
Valida i prompt e gli URL delle immagini localmente per evitare risposte 400.
Ruota i token dell'API Ketchup se l'autenticazione inizia a fallire.
Controlla lo stato del lavoro non più di una volta al secondo per rispettare i limiti di velocità.
Preferisci i webhook per esecuzioni ad alto volume così l'API Ketchup può inviare aggiornamenti.

Esempio di Gestione Errori (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;
  }
}