LogoGemimg AI

专业API参考

Gemimg AI - Nano Banana Pro 企业级图片创作API完整文档

概述

Gemimg AI 专业API为企业和开发者提供Nano Banana Pro驱动的专业图片创作能力。支持文本提示词生图、参考图风格转换、批量处理和企业级工作流集成。

基础 URL

https://gemimg.art/api/v1

企业级身份验证

所有API请求需要使用API密钥进行Bearer Token认证：

Authorization: Bearer YOUR_PROFESSIONAL_API_KEY

从您的专业版控制台生成API密钥。企业用户可申请专用Token以获得更高速率限制。

专业图片创作端点

使用Nano Banana Pro技术进行专业级文本提示词生图创作。

端点

POST /api/v1/professional/generate

请求体（专业版）

{
  "prompt": "现代简约别墅外观，北欧设计美学，蓝调时刻，室内暖光对比，f/11景深，4K超高清",
  "negativePrompt": "模糊, 噪点, 曝光过度, 畸变",
  "mode": "text_to_image",
  "resolution": "4K",
  "outputFormat": "png",
  "aspectRatio": "16:9",
  "colorSpace": "Adobe_RGB",
  "seed": 12345,
  "styleStrength": 0.8,
  "priority": "high"
}

专业参数说明

参数类型必需描述
promptstring是专业创作提示词（支持摄影术语，最多5000字符）
negativePromptstring否负面提示词，排除不想要的元素
modestring是text_to_image 或 image_transformation
resolutionstring否4K、2K、FHD（默认：4K）
outputFormatstring否png、jpeg、webp（默认：png）
aspectRatiostring否16:9、4:3、1:1、9:16等
colorSpacestring否sRGB 或 Adobe_RGB（专业版）
seedinteger否随机种子值（用于复现结果）
styleStrengthfloat否风格强度 0.1-1.0（默认：0.7）
prioritystring否normal、high、urgent（专业版）

响应示例

{
  "success": true,
  "taskId": "prof_task_abc123xyz",
  "status": "queued",
  "priority": "high",
  "estimatedTime": 55,
  "creditsUsed": 3,
  "webhook": "https://your-domain.com/callback"
}

参考图风格转换

专业级参考图应用与风格转换API。

端点

POST /api/v1/professional/transform

请求体（参考图转换）

{
  "prompt": "将产品照片转换为时尚杂志风格，高饱和度，保持产品位置和光影",
  "mode": "image_transformation",
  "referenceImages": [
    {
      "url": "https://your-cdn.com/product-original.jpg",
      "weight": 0.7,
      "role": "composition"
    },
    {
      "url": "https://your-cdn.com/fashion-style-ref.jpg",
      "weight": 0.3,
      "role": "style"
    }
  ],
  "resolution": "4K",
  "outputFormat": "png",
  "colorSpace": "Adobe_RGB"
}

参考图参数

参数类型必需描述
referenceImagesarray是最多2张参考图，每张最大20MB
referenceImages[].urlstring是参考图URL（支持HTTPS）
referenceImages[].weightfloat否权重0.1-0.9（默认：0.5）
referenceImages[].rolestring否composition 或 style

支持的专业格式

  • 输入：JPEG、PNG、WebP、TIFF、RAW（自动转换）
  • 输出：PNG（无损）、JPEG（90-95%）、WebP（优化）
  • 最大尺寸：单张20MB，支持16位色深

批量创作处理

企业级批量生成API，支持并行处理30-50个任务。

端点

POST /api/v1/professional/batch

批量请求体

{
  "batch": [
    {
      "id": "item_001",
      "prompt": "产品A专业摄影，白色背景，4K输出",
      "resolution": "4K"
    },
    {
      "id": "item_002",
      "prompt": "产品B专业摄影，白色背景，4K输出",
      "resolution": "4K"
    }
  ],
  "priority": "high",
  "webhookUrl": "https://your-domain.com/batch-callback"
}

批量响应

{
  "success": true,
  "batchId": "batch_xyz789",
  "totalTasks": 2,
  "estimatedTime": 120,
  "creditsRequired": 6,
  "status": "processing",
  "webhook": "https://your-domain.com/batch-callback"
}

任务状态查询

查询任务实时处理状态和进度。

端点

GET /api/v1/professional/task/{taskId}

响应（处理中）

{
  "success": true,
  "taskId": "prof_task_abc123xyz",
  "status": "processing",
  "progress": 75,
  "estimatedTimeRemaining": 15,
  "message": "正在渲染4K超高清输出..."
}

响应（已完成）

{
  "success": true,
  "taskId": "prof_task_abc123xyz",
  "status": "completed",
  "result": {
    "imageUrl": "https://cdn.gemimg.top/prof/abc123.png",
    "downloadUrl": "https://gemimg.art/api/v1/download/abc123",
    "resolution": "3840x2160",
    "format": "png",
    "colorSpace": "Adobe_RGB",
    "fileSize": 8456320,
    "seed": 12345,
    "creditsUsed": 3
  },
  "metadata": {
    "prompt": "原始提示词...",
    "generationTime": 58,
    "modelVersion": "nano-banana-2.0"
  }
}

状态值

  • queued: 已排队，等待处理
  • processing: 正在生成中
  • completed: 已完成，可下载
  • failed: 生成失败
  • cancelled: 已取消

Webhook集成

企业级Webhook通知系统，实时获取任务完成状态。

Webhook配置

POST /api/v1/professional/webhooks
{
  "url": "https://your-domain.com/gemimg-callback",
  "events": ["task.completed", "task.failed", "batch.completed"],
  "secret": "your_webhook_secret"
}

Webhook负载示例

{
  "event": "task.completed",
  "timestamp": "2025-11-07T10:05:00Z",
  "taskId": "prof_task_abc123xyz",
  "result": {
    "imageUrl": "https://cdn.gemimg.top/prof/abc123.png",
    "resolution": "4K",
    "creditsUsed": 3
  },
  "signature": "sha256_hash_for_verification"
}

Webhook验证

使用HMAC SHA256验证Webhook真实性：

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    computed = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

错误处理

专业版错误响应

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "积分不足，需要3积分，当前余额0",
    "details": {
      "required": 3,
      "current": 0
    },
    "retryAfter": null
  }
}

专业版错误代码

代码HTTP状态描述建议处理
INVALID_API_KEY401API密钥无效或已过期检查密钥有效性
INSUFFICIENT_CREDITS402积分不足充值后重试
INVALID_PARAMS400参数格式错误检查请求体
INVALID_IMAGE_URL400参考图URL无效或无法访问检查图片URL
RATE_LIMIT_EXCEEDED429超出速率限制等待或升级套餐
PROCESSING_ERROR500服务器处理错误重试或联系支持

速率限制

企业级速率限制策略：

套餐每分钟请求批量处理优先队列Webhook
专业版100次/分钟30任务2x速度✅
企业版500次/分钟50任务3x速度✅
定制版自定义无限制专用服务器✅

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

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699286400
X-RateLimit-Priority: high

SDK与集成

官方SDK

专业版SDK支持主流编程语言：

# Node.js
npm install @gemimg/professional-sdk

# Python
pip install gemimg-professional

# PHP
composer require gemimg/professional-sdk

# Go
go get github.com/gemimg/professional-go-sdk

Node.js示例（企业级）

const { GemimgProfessional } = require('@gemimg/professional-sdk');

const client = new GemimgProfessional({
  apiKey: 'YOUR_PROFESSIONAL_API_KEY',
  webhookUrl: 'https://your-domain.com/callback'
});

// 专业创作
const result = await client.generate({
  prompt: '建筑效果图渲染，北欧风格，4K超高清，f/11景深',
  resolution: '4K',
  colorSpace: 'Adobe_RGB',
  priority: 'high',
  styleStrength: 0.8
});

console.log('任务ID:', result.taskId);
console.log('预计时间:', result.estimatedTime);

Python示例（批量处理）

from gemimg_professional import ProfessionalClient

client = ProfessionalClient(api_key='YOUR_API_KEY')

# 批量创作
batch = client.batch_generate([
    {
        'id': 'product_001',
        'prompt': '产品A专业摄影，白色背景，4K输出'
    },
    {
        'id': 'product_002',
        'prompt': '产品B专业摄影，白色背景，4K输出'
    }
], priority='high')

print(f'批量ID: {batch.batch_id}')
print(f'总任务数: {batch.total_tasks}')

最佳实践

专业创作工作流建议

  1. 提示词优化

    • 使用专业摄影术语（光圈、快门、ISO）
    • 包含明确的输出规格（4K、色彩空间）
    • 使用负面提示词排除缺陷

  2. 批量处理优化

    • 批量提交30-50个任务获得最佳性能
    • 使用模板化提示词提高一致性
    • 配置Webhook避免频繁轮询

  3. 参考图应用

    • 合理设置权重（构图0.7 + 风格0.3）
    • 使用高质量输入图（最好4K以上）
    • 选择Adobe RGB色彩空间用于印刷

  4. 错误处理

    • 实现指数退避重试策略
    • 监控速率限制头部
    • 缓存生成结果避免重复

  5. 性能优化

    • 使用CDN加速图片访问
    • 启用Webhook减少API调用
    • 专业版用户使用优先队列

企业支持

专业版和企业版用户享受优先技术支持：

SLA保障

套餐可用性响应时间支持级别
专业版99.5%4小时邮件/工单
企业版99.9%1小时邮件/工单/电话
定制版99.95%30分钟7x24专属支持

开始使用Gemimg AI - Nano Banana Pro 专业API，构建企业级图片创作应用！

需要帮助？联系我们的专业技术团队。

专业创作最佳实践

使用 Gemimg AI - Nano Banana Pro 进行专业级图片创作的高级技巧

专业创作者常见问题

Gemimg AI - Nano Banana Pro 专业级图片创作平台常见问题解答