Руководство разработчика Ketchup API (Google Nano Banana 2)

Разрабатывайте быстро с пошаговыми инструкциями, примерами запросов и лучшими практиками для работы с изображениями в Ketchup API.

Посмотреть цены Ketchup APIСравнить планы и тарифы Ketchup API.

Обзор Ketchup API

Ketchup API создает продуктовые фото, фоны для интерфейсов и графику для соцсетей с предсказуемым качеством. REST-дизайн упрощает интеграцию, а платформа масштабируется от индивидуальных разработчиков до корпоративных запусков.

Возможности Ketchup API

Генерация изображений из текста, настроенная для продуктовых сцен с моделями Ketchup API.
Редактирование по образцу с поддержкой до пяти изображений в одном запросе Ketchup API.
Асинхронная очередь задач, чтобы ваше приложение оставалось отзывчивым во время рендеринга Ketchup API.
Webhook-уведомления, которые позволяют Ketchup API отправлять изменения статуса в реальном времени.
Единообразные JSON-схемы, которые упрощают обработку ответов Ketchup API.
Безопасность Bearer-токенов, управляемая в панели Ketchup API.

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

Начало работы с Ketchup API

Откройте рабочее пространство Ketchup API и создайте токен доступа.
Добавьте Bearer-токен Ketchup API в заголовок Authorization для каждого вызова.
Отправьте POST-запрос к эндпоинту генерации изображений Ketchup API с промптами, режимом и ссылками.
Сохраните возвращенный ID задачи и опрашивайте эндпоинт статуса или подпишитесь на webhooks.
Скачайте готовые файлы, когда Ketchup API отметит задачу как успешную.

Аутентификация

Каждый запрос к Ketchup API требует действительный Bearer токен. Меняйте ключи для каждой среды и регулярно проверяйте использование.

Метод Bearer Token

Прикрепите ваш токен Ketchup API к заголовку Authorization, как показано ниже:

Authorization: Bearer <your-api-key>

Пример формата токена

Authorization: Bearer dk-1234567890abcdef

Пример запроса

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

Чек-лист действительного токена

✅ Токен активен и не истёк.
✅ Рабочая область имеет доступ к Ketchup API.
✅ Аккаунт имеет оставшуюся квоту или кредиты.

Частые проблемы

❌ Отсутствует заголовок Authorization.
❌ Неверный формат значения Bearer токена.
❌ Заблокированная рабочая область или отозванный токен.

Генерация изображений Ketchup API

Создавайте новые рендеры, изменяйте существующие ресурсы или смешивайте мудборды с помощью конечной точки генерации Ketchup API.

Конечная точка

POST /api/image/gen

Параметры запроса

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

Примеры кода

Базовый промпт Ketchup API

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

Ремикс Ketchup API с референсами

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

Схема ответа

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

Обработка ошибок

400 - Bad Request

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

401 - Unauthorized

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

Статус задания Ketchup API

Отслеживайте прогресс рендеринга и получайте URL для загрузки с помощью конечной точки статуса.

Конечная точка

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

Параметры запроса

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

Пример запроса

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

Коды статуса

pending - Ketchup API принял запрос и поставил задание в очередь.

submitted - Ketchup API запланировал задание для обработки.

in_progress - Ketchup API сейчас рендерит ресурсы.

success - Ketchup API завершил рендеринг и ресурсы готовы к загрузке.

failed - Ketchup API не смог выполнить задание из-за ошибки.

Коды ошибок

404 - Task Not Found

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

401 - Unauthorized

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

Модели данных Ketchup API

Подробные схемы для полезной нагрузки запросов, ответов задач и тел webhook, используемых в интеграциях Ketchup API.

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

Схемы моделей

google/gempix2Nano Banana image generation model

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

Устранение неполадок

Понимание форматов ошибок Ketchup API, правил повторных попыток и когда обращаться в поддержку.

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

Лучшие практики

Проверяйте HTTP код состояния перед разбором полезной нагрузки.
Используйте экспоненциальную задержку при повторных попытках задач Ketchup API после ошибок 500.
Записывайте ID запроса, чтобы команда поддержки Ketchup API могла отследить проблемы.
Проверяйте промпты и URL изображений локально, чтобы избежать ответов 400.
Ротируйте токены Ketchup API, если аутентификация начинает сбоить.
Опрашивайте статус задач не чаще одного раза в секунду, чтобы соблюдать ограничения скорости.
Предпочитайте webhook для высоконагруженных операций, чтобы Ketchup API мог отправлять обновления.

Пример обработки ошибок (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;
  }
}