生成图片

从文字或图片创建新的 AI 图片。

端点

POST /generate-image

请求体

{
  "generationType": "text_to_image" - "image_to_image",
  "prompt": "您的图片描述",
  "aspectRatio": "auto" - "16:9" - "9:16",
  "imageUrl": "https://...", // 如果 generationType 为 "image_to_image" 则必需
  "imageKey": "r2-key" // 可选，用于已上传的图片
}

| 参数 - 类型 - 必需 - 描述 | |------|------|------|------| | generationType - string - 是 - 生成类型：text_to_image 或 image_to_image | | prompt - string - 是 - 您想要生成的图片描述 | | aspectRatio - string - 否 - 图片宽高比。默认值：auto | | imageUrl - string - 条件 - 如果 generationType 为 image_to_image 则必需 | | imageKey - string - 否 - 已上传图片的存储密钥 |

响应

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "images-uuid-123",
    "status": "pending",
    "generationType": "text_to_image",
    "prompt": "您的图片描述",
    "aspectRatio": "16:9",
    "createdAt": "2025-10-16T10:00:00Z"
  }
}

示例

curl -X POST https://gempix2ai.site/api/generate-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generationType": "text_to_image",
    "prompt": "美丽的海上日落，海浪轻轻拍打着海岸",
    "aspectRatio": "16:9"
  }'

获取图片状态

检查图片生成请求的状态。

端点

GET /images-status/{uuid}

参数

| 参数 - 类型 - 必需 - 描述 | |------|------|------|------| | uuid - string - 是 - 生成请求返回的图片 UUID |

响应

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "images-uuid-123",
    "status": "completed" - "pending" - "processing" - "failed",
    "imageUrl": "https://...", // 状态为 "completed" 时可用
    "progress": 85, // 处理进度 (0-100)
    "estimatedTime": 120 // 预计剩余秒数
  }
}

状态值

pending: 图片已排队等待处理
processing: 图片正在生成中
completed: 图片已完成并可供下载
failed: 生成失败（查看错误消息）

上传图片

上传图片用于图片转图片生成。

端点

POST /upload-image-image

请求

使用 multipart/form-data 上传图片文件。

curl -X POST https://gempix2ai.site/api/upload-image-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

响应

{
  "code": 0,
  "msg": "上传成功",
  "data": {
    "imageUrl": "https://...",
    "imageKey": "r2-key-123"
  }
}

支持的格式

JPEG/JPG
PNG
WebP
最大文件大小：50MB

错误代码

| 代码 - 描述 | |------|------| | 0 - 成功 | | 1000 - 无效参数 | | 1001 - 积分不足 | | 1002 - 身份验证失败 | | 1003 - 超出速率限制 | | 5000 - 服务器错误 |

错误响应示例

{
  "code": 1001,
  "msg": "积分不足",
  "data": {
    "required": 2,
    "current": 0
  }
}

速率限制

免费版: 10 请求/小时
入门版: 100 请求/小时
专业版: 500 请求/小时
企业版: 自定义限制

所有响应中都包含速率限制标头：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1697472000

SDK 和库

我们为流行的编程语言提供官方 SDK：

JavaScript/TypeScript: npm install @gempix2-friendly/sdk
Python: pip install gempix2-friendly
Go: go get github.com/gempix2-friendly/go-sdk

JavaScript 示例

import { Veo3o1 } from '@gempix2-friendly/sdk';

const client = new Veo3o1('YOUR_API_KEY');

const images = await client.generateImage({
  generationType: 'text_to_image',
  prompt: '美丽的海上日落',
  aspectRatio: '16:9'
});

console.log('图片 UUID:', images.uuid);

Webhooks

配置 webhooks 以在图片完成时接收通知。

设置

前往 API 设置
输入您的 webhook URL
选择要接收的事件

事件类型

images.completed: 图片生成成功完成
images.failed: 图片生成失败

Webhook 负载

{
  "event": "images.completed",
  "uuid": "images-uuid-123",
  "imageUrl": "https://...",
  "timestamp": "2025-10-16T10:05:00Z"
}

最佳实践

合理轮询: 每 5-10 秒检查一次图片状态，而不是连续检查
处理错误: 实现带指数退避的重试逻辑
缓存结果: 存储生成的图片以避免重复生成
使用 webhooks: 比轮询更高效的完成通知方式
验证输入: 在 API 调用之前检查提示词长度和图片格式

支持

需要 API 帮助？

📧 邮箱：api-support@gempix2ai.site
📚 加入我们的开发者 Discord
💬 联系支持

API 参考文档

概述

基础 URL

身份验证