GemPix2 API 概览
GemPix2 图像生成 API 提供对 Google Gemini AI 模型的访问，用于从文本提示和参考图像生成高质量图像。我们的 GemPix2 服务提供简单的 RESTful 接口，具有全面的任务管理和回调支持。
GemPix2 主要特性
- • GemPix2 使用 Google Gemini AI 模型进行文本到图像生成
- • GemPix2 支持参考图像（最多4张）
- • GemPix2 异步任务处理与状态跟踪
- • GemPix2 支持实时通知的 Webhook 回调
- • GemPix2 基于 JSON 的 RESTful API
- • GemPix2 Bearer 令牌认证
overview.base_url
https://api.defapi.orgoverview.api_version
v1.0.0GemPix2 快速开始
- 1. 在生产服务器注册获取 GemPix2 API 密钥
- 2. 在授权头中包含您的 GemPix2 API 密钥
- 3. 向 GemPix2 图像生成端点发送 POST 请求
- 4. 使用返回的 GemPix2 task_id 检查生成状态
- 5. 任务完成后获取 GemPix2 生成的图像
认证方式
所有 API 请求都必须使用 Bearer 令牌认证。在每个请求的授权头中包含您的 API 密钥。
认证方法
通过在授权头中包含您的 API 密钥来使用 HTTP Bearer 令牌认证：
Authorization: Bearer <your-api-key>API 密钥格式示例
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"
}'有效认证
- ✅ API 密钥有效
- ✅ 用户账户处于活跃状态
- ✅ 有足够的积分
常见错误
- ❌ 缺少 API 密钥
- ❌ API 密钥格式无效
- ❌ 账户已过期或未激活
GemPix2 图像生成 API
使用 GemPix2 和 Google Gemini AI 模型生成图像，支持自定义提示和参考图像。
端点
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 |
请求示例
基础 GemPix2 图像生成
{
"model": "google/gempix2",
"prompt": "A beautiful girl dancing in a garden"
}GemPix2 基于参考图像的生成
{
"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"}GemPix2 任务查询 API
使用从 GemPix2 图像生成端点返回的任务 ID 查询 GemPix2 图像生成任务的状态和结果。
端点
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"
GemPix2 任务状态值
pending - GemPix2 任务已创建，等待处理submitted - GemPix2 任务已提交到生成队列in_progress - GemPix2 任务正在处理中success - GemPix2 任务成功完成，已生成图像failed - GemPix2 任务因错误而失败错误响应
404 - Task Not Found
{"code": 1, "message": "task not found"}401 - Unauthorized
{"code": 401, "message": "Invalid API key"}GemPix2 数据模型
GemPix2 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 |
GemPix2 可用模型
google/gempix2Nano Banana image generation modelgoogle/gemini-2.5-flash-imageGemini 2.5 Flash image model错误处理
处理错误和理解 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
错误处理最佳实践
- 1. 在处理响应体之前始终检查 HTTP 状态代码:
- 2. 对 500 错误实施指数退避重试逻辑:
- 3. 记录包含详细信息的错误响应以便调试:
- 4. 发送请求前验证输入以避免 400 错误:
- 5. 通过提示用户更新 API 密钥来处理认证错误:
- 6. 定期监控任务状态而不是过于频繁地轮询:
- 7. 尽可能使用 webhooks 来避免轮询任务完成状态:
错误处理示例 (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;
}
}