Ketchup API

Guia do Desenvolvedor da API Ketchup (Google Nano Banana 2)

Desenvolva rapidamente com tutoriais, exemplos de payload e melhores práticas criadas para fluxos de trabalho de imagens da API Ketchup.

Ver Preços da API KetchupCompare planos e níveis de uso da API Ketchup.

Visão Geral da API Ketchup

A API Ketchup oferece fotos de produtos, fundos de UI e gráficos para redes sociais com qualidade de renderização previsível. O design REST mantém as integrações simples, enquanto a plataforma escala desde criadores solo até lançamentos empresariais.

Capacidades da API Ketchup

  • Geração de texto para imagem ajustada para cenários de produção com modelos da API Ketchup.
  • Edição guiada por referência com até cinco imagens em uma única solicitação da API Ketchup.
  • Fila de trabalhos assíncrona para que seu app permaneça responsivo enquanto a API Ketchup renderiza.
  • Callbacks de webhook que permitem à API Ketchup enviar mudanças de status em tempo real.
  • Esquemas JSON consistentes que mantêm as respostas da API Ketchup fáceis de analisar.
  • Segurança de token Bearer gerenciada no painel da API Ketchup.

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

Começando com a API Ketchup

  1. Abra um workspace da API Ketchup e crie um token de acesso.
  2. Adicione o token Bearer da API Ketchup ao cabeçalho Authorization para cada chamada.
  3. Faça POST para o endpoint de geração de imagens da API Ketchup com prompts, modo e referências.
  4. Armazene o ID do trabalho retornado e consulte o endpoint de status ou assine webhooks.
  5. Baixe os arquivos finais quando a API Ketchup marcar o trabalho como sucesso.

Autenticação

Toda requisição da API Ketchup precisa de um token Bearer válido. Rotacione as chaves por ambiente e audite o uso frequentemente.

Método de Token Bearer

Anexe seu token da API Ketchup ao cabeçalho Authorization como mostrado abaixo:

Authorization: Bearer <your-api-key>

Exemplo de Formato de Token

Authorization: Bearer dk-1234567890abcdef

Requisição de Exemplo

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 Verificação de Token Válido

  • ✅ Token está ativo e não expirou.
  • ✅ Workspace tem acesso à API Ketchup habilitado.
  • ✅ Conta tem cota restante ou crédito.

Problemas Comuns

  • ❌ Cabeçalho Authorization ausente.
  • ❌ Valor de token Bearer mal formatado.
  • ❌ Workspace suspenso ou token revogado.

Geração de Imagem da API Ketchup

Crie renders novos, revise assets existentes ou misture mood boards com o endpoint de geração da API Ketchup.

Endpoint

POST /api/image/gen

Parâmetros da Requisição

ParameterTypeRequiredDescription
modelstringYesModel identifier (e.g., "google/gempix2")
promptstringYesText prompt describing the image
imagesarrayNoReference image URLs (max 4)
callback_urlstringNoWebhook URL for completion notifications

Exemplos de Código

Prompt Básico da API Ketchup

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

Remix da API Ketchup com Referências

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

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

Tratamento de Erros

400 - Bad Request

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

401 - Unauthorized

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

Status do Job da API Ketchup

Monitore o progresso de renderização e obtenha URLs de entrega usando o endpoint de status.

Endpoint

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

Parâmetros de Consulta

ParameterTypeRequiredDescription
task_idstringYesUnique task identifier returned from generation endpoint

Requisição de Exemplo

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 Status

pending - A API Ketchup aceitou a requisição e colocou o job na fila.
submitted - A API Ketchup agendou o job para processamento.
in_progress - A API Ketchup está renderizando assets agora.
success - A API Ketchup terminou de renderizar e os assets estão prontos para download.
failed - A API Ketchup não conseguiu renderizar o job devido a um erro.

Códigos de Erro

404 - Task Not Found

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

401 - Unauthorized

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

Modelos de Dados da API Ketchup

Esquemas detalhados para payloads de requisição, respostas de trabalhos e corpos de webhook usados em integrações da API Ketchup.

ImageGenResult

Represents a generated image result.

{
  "image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
}
FieldTypeDescription
imagestringImage 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
  }
}
FieldTypeDescription
resultarrayArray of ImageGenResult objects (null if failed)
statusstringFinal task status (success/failed)
task_idstringUnique task identifier
consumedstringCredits consumed by the task
status_reasonobjectStatus 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

Resolução de Problemas

Entenda os formatos de erro da API Ketchup, regras de retry e quando escalar para o suporte.

Códigos de Status 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

Melhores Práticas

  1. Verifique o código de status HTTP antes de analisar o payload.
  2. Use backoff exponencial ao tentar novamente trabalhos da API Ketchup após erros 500.
  3. Registre o ID da requisição para que a equipe de suporte da API Ketchup possa rastrear problemas.
  4. Valide prompts e URLs de imagem localmente para evitar respostas 400.
  5. Rotacione os tokens da API Ketchup se a autenticação começar a falhar.
  6. Consulte o status do trabalho no máximo uma vez por segundo para respeitar os limites de taxa.
  7. Prefira webhooks para execuções de alto volume para que a API Ketchup possa enviar atualizações.

Exemplo de Tratamento de Erros (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;
  }
}