Ketchup API (Google Nano Banana 2) 开发者指南

通过详细教程、示例数据和最佳实践，快速构建 Ketchup API 图像工作流程。

查看 Ketchup API 价格比较 Ketchup API 套餐和使用层级。

Ketchup API 概览

Ketchup API 为产品图、UI 背景和社交图片提供稳定的渲染质量。REST 设计让集成变得简单，平台可从个人开发者扩展到企业级应用。

Ketchup API 功能

使用 Ketchup API 模型进行文本转图像生成，专为生产场景优化。
参考引导编辑，单次 Ketchup API 请求最多支持五张图像。
异步任务队列，让你的应用在 Ketchup API 渲染时保持响应。
Webhook 回调，让 Ketchup API 实时推送状态变更。
一致的 JSON 结构，让 Ketchup API 响应易于解析。
在 Ketchup API 控制台管理 Bearer token 安全。

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

Ketchup API 入门

打开 Ketchup API 工作区并创建访问令牌。
在每次调用的 Authorization 头中添加 Ketchup API Bearer token。
向 Ketchup API 图像生成端点发送 POST 请求，包含提示词、模式和参考图。
保存返回的任务 ID，轮询状态端点或订阅 webhooks。
当 Ketchup API 标记任务为成功时下载最终文件。

身份验证

每个 Ketchup API 请求都需要有效的 Bearer 令牌。请为每个环境轮换密钥并经常审计使用情况。

Bearer 令牌方法

将您的 Ketchup API 令牌附加到授权头，如下所示：

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 访问。
✅ 账户有剩余配额或积分。

常见问题

❌ 缺少授权头。
❌ 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 数据模型

详细的请求负载、作业响应和 Ketchup API 集成中使用的 webhook 主体架构。

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 状态码。
遇到 500 错误后重试 Ketchup API 作业时使用指数退避策略。
记录请求 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;
  }
}