Ketchup API開発者ガイド
Ketchup API画像ワークフロー用のチュートリアル、サンプルペイロード、ベストプラクティスで高速開発を実現。
Ketchup API料金を見るKetchup APIプランと使用量レベルを比較。
Ketchup API概要
Ketchup APIは予測可能なレンダリング品質で商品画像、UI背景、ソーシャルグラフィックスを作成します。RESTデザインで統合をシンプルに保ち、個人開発者から企業ローンチまでスケールします。
Ketchup API機能
- Ketchup APIモデルでプロダクションシーンに最適化されたテキストから画像生成。
- 単一のKetchup APIリクエストで最大5枚の画像を使った参照ガイド編集。
- Ketchup APIがレンダリング中でもアプリの応答性を保つ非同期ジョブキュー。
- Ketchup APIがリアルタイムでステータス変更をプッシュするWebhookコールバック。
- Ketchup APIレスポンスの解析を簡単にする一貫したJSONスキーマ。
- Ketchup APIダッシュボードで管理されるBearerトークンセキュリティ。
overview.base_url
https://api.defapi.orgoverview.api_version
v1.0.0Ketchup API入門
- Ketchup APIワークスペースを開いてアクセストークンを作成。
- すべての呼び出しでAuthorizationヘッダーにKetchup API Bearerトークンを追加。
- プロンプト、モード、参照でKetchup API画像生成エンドポイントにPOST。
- 返されたジョブIDを保存し、ステータスエンドポイントをポーリングまたはWebhookを登録。
- Ketchup APIがジョブを成功としてマークしたら最終ファイルをダウンロード。
認証
すべてのKetchup APIリクエストには有効なBearerトークンが必要です。環境ごとにキーをローテーションし、使用状況を定期的に監査してください。
Bearerトークン方式
以下に示すように、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 データモデル
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 modelgoogle/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ジョブを再試行する際は指数バックオフを使用してください。
- Ketchup APIサポートチームが問題を追跡できるようにリクエストIDをログに記録してください。
- 400レスポンスを避けるため、プロンプトと画像URLをローカルで検証してください。
- 認証が失敗し始めた場合はKetchup APIトークンをローテーションしてください。
- レート制限を尊重するため、ジョブステータスのポーリングは1秒に1回以下にしてください。
- 高ボリュームの実行では、Ketchup APIが更新をプッシュできるようにWebhookを優先してください。
サンプルエラーハンドリング（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;
}
}