Image Gateway

管理员登录

请输入管理员密钥后进入后台。

Image Gateway

正在读取后台数据

总览

总请求数
0
成功请求
0
失败请求
0
累计计费积分
0
系统盘剩余空间
0 B
数据盘剩余空间
0 B
图片目录占用
0 B
图片文件数量
0

-

图片自动归档

执行计划
-
-
累计归档
0
-
累计节省
0 B
-
最近执行
-
-

-

渠道日常测试

执行计划
-
-
下次执行
-
-
最近批次
-
-
上游渠道 最近测试时间 状态 Provider 模型 / 尺寸 耗时 输出 可能原因 错误
时间 上游渠道 状态 Provider 模型 / 尺寸 耗时 可能原因 错误

渠道 Key

渠道 Key 状态 说明 请求数 成功 失败 积分 最近使用 操作

渠道配置

出图历史

时间 渠道 图片 操作 尺寸 积分 Provider 状态 耗时 提示词 错误

Providers

ID 类型 模型 优先级 能力 状态 操作

Provider 配置

Routes

ID 操作 档位 模型匹配 Provider 链 状态 操作

Route 配置

Provider Attempts

时间 Job 渠道 Provider 操作 尺寸 状态 耗时 错误

API 对接文档

基础信息

Base URL

http://116.62.115.102:8787/v1

鉴权方式

Authorization: Bearer 渠道Key

支持模型

  • gpt-image-2
  • gpt-image-2-vip
  • firefly-gpt-image-2

积分规则

  • 1k = 1分
  • 2k = 7分
  • 4k = 12分

后台会根据请求尺寸自动识别档位，并按渠道统计使用量。

1. 查询模型

GET /models

curl -X GET "http://116.62.115.102:8787/v1/models" ^
  -H "Authorization: Bearer 你的渠道Key"

返回示例

{
  "object": "list",
  "data": [
    { "id": "gpt-image-2", "object": "model", "owned_by": "image-gateway" },
    { "id": "gpt-image-2-vip", "object": "model", "owned_by": "image-gateway" },
    { "id": "firefly-gpt-image-2", "object": "model", "owned_by": "image-gateway" }
  ]
}

2. 文生图接口

POST /images/generations

curl -X POST "http://116.62.115.102:8787/v1/images/generations" ^
  -H "Authorization: Bearer 你的渠道Key" ^
  -H "Content-Type: application/json" ^
  -d "{
    \"model\": \"gpt-image-2\",
    \"prompt\": \"一张极简风格的产品展示图\",
    \"size\": \"1024x1024\",
    \"response_format\": \"url\"
  }"

常用参数

  • model: 模型名，必传
  • prompt: 提示词，必传
  • size: 例如 1024x1024、1536x2048、2048x2048，必传，当前实际尺寸、分桶和路由判断仍以 size 为主
  • response_format: 建议用 url，也可用 b64_json，建议传
  • resolution: 例如 1k / 2k / 4k，建议传
  • aspectRatio: 例如 1:1 / 3:4 / 9:16，建议传
  • quality: 例如 low / medium / high，建议传

建议调用方把 resolution、aspectRatio、quality 也一起传上来，方便后台记录、联调排查和后续扩路由。当前不传也不会影响现有请求执行。

这是同步接口，请求会一直等到出图成功或失败后才返回。

3. 图生图 / 编辑接口

POST /images/edits

这是 multipart/form-data 请求，至少带 1 张图片。

curl -X POST "http://116.62.115.102:8787/v1/images/edits" ^
  -H "Authorization: Bearer 你的渠道Key" ^
  -F "image=@example.png" ^
  -F "prompt=把这张图做成高级感海报风格" ^
  -F "model=gpt-image-2" ^
  -F "size=1024x1024" ^
  -F "response_format=url"

推荐完整示例

curl -X POST "http://116.62.115.102:8787/v1/images/edits" ^
  -H "Authorization: Bearer 你的渠道Key" ^
  -F "image=@C:\images\ref1.png" ^
  -F "image=@C:\images\ref2.png" ^
  -F "mask=@C:\images\mask.png" ^
  -F "prompt=按参考图重绘一张高级感人像海报" ^
  -F "model=gpt-image-2" ^
  -F "size=1152x1536" ^
  -F "resolution=1k" ^
  -F "aspectRatio=3:4" ^
  -F "quality=high" ^
  -F "response_format=url"

可选字段

  • image: 支持多张
  • mask: 可选遮罩图
  • prompt: 编辑说明
  • model / size / response_format
  • resolution / aspectRatio / quality: 建议同时传，当前默认只用于记录和联调，不会因为传了这些值而改变现有路由

这是同步接口，如果上游出图很慢，调用链中任何一层 HTTP 超时都可能导致客户端先断开。

4. 异步提交接口

推荐给容易超过 60 秒的调用方使用。接口会先返回 gateway_job_id，再由客户端轮询查询结果。

POST /images/generations/submit

curl -X POST "http://116.62.115.102:8787/v1/images/generations/submit" ^
  -H "Authorization: Bearer 你的渠道Key" ^
  -H "Content-Type: application/json" ^
  -d "{
    \"model\": \"gpt-image-2\",
    \"prompt\": \"一张极简风格的产品展示图\",
    \"size\": \"1024x1024\",
    \"resolution\": \"1k\",
    \"aspectRatio\": \"1:1\",
    \"quality\": \"high\",
    \"response_format\": \"url\"
  }"

POST /images/edits/submit

参数与同步版 /images/edits 一致，也是 multipart/form-data。

异步图生图完整示例

curl -X POST "http://116.62.115.102:8787/v1/images/edits/submit" ^
  -H "Authorization: Bearer 你的渠道Key" ^
  -F "image=@C:\images\ref1.png" ^
  -F "image=@C:\images\ref2.png" ^
  -F "mask=@C:\images\mask.png" ^
  -F "prompt=按参考图重绘一张高级感人像海报" ^
  -F "model=gpt-image-2" ^
  -F "size=1152x1536" ^
  -F "resolution=1k" ^
  -F "aspectRatio=3:4" ^
  -F "quality=high" ^
  -F "response_format=url"

提交成功示例

{
  "success": true,
  "status": "accepted",
  "job_status": "running",
  "message": "任务已提交，请轮询查询结果",
  "gateway_job_id": "3b128444297e4009b8a24f6f1fb566ad",
  "poll_url": "http://116.62.115.102:8787/v1/jobs/3b128444297e4009b8a24f6f1fb566ad"
}

5. 查询异步任务

GET /jobs/{gateway_job_id}

curl -X GET "http://116.62.115.102:8787/v1/jobs/3b128444297e4009b8a24f6f1fb566ad" ^
  -H "Authorization: Bearer 你的渠道Key"

PowerShell 轮询示例

$headers = @{ Authorization = "Bearer 你的渠道Key" }
$jobId = "3b128444297e4009b8a24f6f1fb566ad"

do {
  $result = Invoke-RestMethod -Method Get -Uri "http://116.62.115.102:8787/v1/jobs/$jobId" -Headers $headers
  $status = $result.status
  Write-Host "job status: $status"
  if ($status -eq "queued" -or $status -eq "running") {
    Start-Sleep -Seconds 5
  }
} while ($status -eq "queued" -or $status -eq "running")

$result | ConvertTo-Json -Depth 10

处理中示例

{
  "success": true,
  "status": "running",
  "done": false,
  "message": "任务处理中",
  "gateway_job_id": "3b128444297e4009b8a24f6f1fb566ad"
}

排队中示例

{
  "success": true,
  "status": "queued",
  "done": false,
  "message": "任务排队中",
  "gateway_job_id": "3b128444297e4009b8a24f6f1fb566ad",
  "job": {
    "queue_reason": "providers temporarily unavailable: vividai_nano_banana_2",
    "retry_after_seconds": 20
  }
}

完成后示例

{
  "success": true,
  "status": "success",
  "done": true,
  "gateway_job_id": "3b128444297e4009b8a24f6f1fb566ad",
  "response": {
    "data": [
      {
        "url": "http://116.62.115.102:8787/files/xxx.png",
        "image_url": "http://116.62.115.102:8787/files/xxx.png"
      }
    ]
  }
}

6. 长请求说明

  • 同步接口适合能稳定等到最终结果的调用方。
  • 如果调用方、反向代理、工作流平台存在 60 秒或 120 秒 HTTP 超时，建议改用异步接口。
  • 异步接口不会因为客户端提前断开而丢失服务器端任务执行结果。
  • resolution、aspectRatio、quality 属于建议传参：网关会记录原始值并计算实际档位和比例；是否发给上游由各 Provider 的请求配置单独决定。

7. 参数传参建议

这三个字段建议业务侧都保留并传上来：

  • resolution: 用于记录业务想走的档位，例如 1k / 2k / 4k
  • aspectRatio: 用于记录业务想要的画幅，例如 1:1 / 3:4 / 9:16
  • quality: 用于记录业务期望质量，例如 low / medium / high

网关会记录它们，但默认仍以 size 作为分桶依据。Provider 可以分别配置尺寸映射和字段透传，不同上游之间互不影响。

{
  "model": "gpt-image-2",
  "prompt": "A clean product photo of a white ceramic mug.",
  "size": "1024x1024",
  "response_format": "url",
  "resolution": "1k",
  "aspectRatio": "1:1",
  "quality": "high"
}

8. Provider 独立请求配置

在 Provider 的扩展 JSON 中配置。normalized 使用网关归一化尺寸，client 使用调用方原始尺寸，mapped 根据实际档位和比例查尺寸表。

{
  "request_profile": {
    "name": "example_upstream",
    "size_strategy": "mapped",
    "size_map": {
      "4k": { "9:21": "1644x3828" }
    },
    "field_map": {
      "resolved_resolution": "resolution",
      "resolved_aspect_ratio": "aspectRatio",
      "quality": "quality"
    },
    "generation": {
      "static_fields": { "background": "auto" }
    },
    "edit": {
      "static_fields": { "input_fidelity": "high" }
    }
  },
  "output_validation": {
    "enabled": true,
    "require_dimensions": true,
    "dimension_tolerance": 0.08,
    "aspect_ratio_tolerance": 0.05
  }
}
  • field_map 只配置上游明确支持的字段；只认 size 的接口不需要填写。
  • 真实图片尺寸超出容差时，该 Provider 会记为失败并继续下一候补。
  • 以后新增渠道一般只需新增 Provider 和配置请求规则，不需要修改公共路由代码。

9. 同步成功返回示例

{
  "created": 1783323640,
  "data": [
    {
      "url": "http://116.62.115.102:8787/files/xxx.png"
    }
  ],
  "success": true,
  "status": "success",
  "message": "出图成功",
  "gateway_job_id": "3b128444297e4009b8a24f6f1fb566ad",
  "client_size_requested": "1024x1024",
  "upstream_size_used": "1254x1254",
  "size_alias_applied": true,
  "provider_request_profile": "vividai_firefly",
  "provider_size_used": "1254x1254",
  "actual_output_sizes": ["1254x1254"],
  "gateway_provider_id": "vividai_gpt_image_2"
}

10. 失败返回示例

{
  "success": false,
  "status": "failed",
  "message": "出图失败: Invalid proxy API key",
  "error": {
    "message": "Invalid proxy API key",
    "type": "invalid_request_error"
  }
}

11. 历史图片归档

  • 每天北京时间 02:00 自动处理超过 7 天的 PNG。
  • 归档格式为 JPEG 质量 88，保持原始宽高不变。
  • 旧 PNG URL 会返回 302 到归档 JPEG，历史链接继续有效。
  • 已归档图片不会重复压缩；透明图片会保留 PNG 并标记为跳过。
POST /api/admin/image-archive/run
Authorization: Bearer ADMIN_API_KEY
Content-Type: application/json

{}