正在打开创作工具

HuGu Draw 正在准备画布、素材与工作台资源，请稍候。

正在进入创作空间

HuGu Draw 正在准备画布、素材与工作台资源，请稍候。

HuGu Draw 4K Creative Engine

API 文档登录 / 注册

HuGu API Docs

图片生成 API 接口文档

对外 API 目前开放图片能力：文生图和图生图。登录后可在 API Keys 页面创建密钥，再把下方 Base URL 接入到你的网站、软件或自动化工作流。

一块画布，完成从灵感到成图

管理 API Keys 充值积分

/api/v1

OpenAI Compatible Base URL

/api

异步任务 Base URL

gpt-image-2

主要模型

当前可用能力

文生图

图生图

OpenAI 兼容调用

gpt-image-2

本页优先展示当前可直接接入的图片 API；更多能力会在稳定开放后补充到文档。

1. 快速开始

Base URL：/api/v1

鉴权方式：推荐使用 Authorization: Bearer YOUR_API_KEY；也兼容 X-Api-Key / X-Access-Key 请求头。

创建密钥：登录后前往 /apikeys 创建 API Key。密钥通常以 ik_ 开头，明文只展示一次，请保存到你的服务端环境变量，不要放到前端源码里。

计费说明：请求成功后按模型单价 × n 扣除积分；上游失败或平台拒绝时会按站内规则退款/不扣费。

2. 模型与适用场景

gpt-image-2

标准图片模型。选择 2K / 4K 时属于高清放大输出，适合日常文生图、图生图、快速创作和成本更可控的批量调用；图生图最多 8 张参考图，总大小不超过 40MB。

3. 文生图：POST /images/generations

使用 JSON 请求体提交提示词。适合从零生成图片、海报、电商主图、角色设定、插画、封面和创意草图。

参数	类型	必填	说明
model	string	是	图片模型 ID，目前开放 gpt-image-2。gpt-image-2 为标准模型，2K / 4K 属于高清放大输出；gpt-image-2-4K 高质量线路为 gpt-image-2-4K 高质量线路，2K / 4K 会以原生高清尺寸参数提交给上游生成，不做本地插值、后期差分或二次放大。
prompt	string	是	生图提示词。建议写清主体、场景、构图、风格、光线、材质、色彩、文字限制和负面要求。
n	number	否	生成张数，默认 1。计费会按生成张数累计；对外调用建议一次 1 张，批量任务由业务侧排队。
size	string	否	比例或尺寸。只支持下方白名单中的 8 种比例和对应明确尺寸；未传或传入不支持尺寸时会按 1:1 安全归一。
quality	string	否	画质偏好，常用 high / medium / low，也兼容 standard。尺寸档位由 size + upscale 决定，quality 不单独决定输出尺寸。
style	string	否	风格倾向，常用 natural / vivid。natural 更自然克制，vivid 更鲜艳强烈。
background	string	否	背景策略，常用 opaque / transparent / auto。透明背景是否可用取决于模型与上游。
response_format	string	否	返回格式，支持 url / b64_json。API Key 同步调用默认 b64_json，以兼容 Cherry Studio；如需图片链接请显式传 url。
output_format	string	否	输出文件格式扩展字段，常用 png / jpeg / webp；平台会透传给上游，实际支持以模型为准。
upscale	string	否	清晰度档位。留空为 1K；可传 2k / 4k。使用 gpt-image-2 时代表高清放大；使用 gpt-image-2-4K 高质量线路时会以对应原生高清尺寸参数请求上游，实际像素随宽高比变化。

图片尺寸白名单

比例	1K	2K	4K
1:1	1024x1024	2048x2048	2880x2880
3:2	1536x1024	2160x1440	3456x2304
2:3	1024x1536	1440x2160	2304x3456
16:9	1280x720	2560x1440	3840x2160
9:16	720x1280	1440x2560	2160x3840
4:3	1024x768	2048x1536	3200x2400
3:4	768x1024	1536x2048	2400x3200
21:9	1920x816	3120x1344	3840x1648

返回 URL 示例

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A realistic sunset cityscape, wet street reflections, cinematic lighting, dense midground details, clean composition",
    "n": 1,
    "size": "16:9",
    "quality": "high",
    "style": "natural",
    "background": "opaque",
    "response_format": "url"
  }'

返回 b64_json 示例（Cherry Studio / Chatbox）

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute orange cat playing with yarn, clean studio lighting",
    "n": 1,
    "size": "1:1",
    "quality": "high",
    "response_format": "b64_json"
  }'

标准模型放大 4K 示例

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean premium product poster, soft commercial lighting, crisp details, minimal beige background",
    "size": "1:1",
    "quality": "high",
    "response_format": "url",
    "output_format": "png",
    "upscale": "4k"
  }'

4K 高质量线路示例

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-4K 高质量线路",
    "prompt": "A premium commercial poster, ultra sharp product details, polished studio lighting, clean luxury background",
    "n": 1,
    "size": "1:1",
    "quality": "high",
    "upscale": "4k",
    "response_format": "url"
  }'

4. 图生图：POST /images/edits

使用 multipart/form-data 上传参考图。单图用 image；多图可以多次传 image[]，也兼容重复传 image 字段。当前图片模型限制：最多 8 张参考图，总大小不超过 40MB。

参数	类型	必填	说明
model	form field	是	图片模型 ID，目前开放 gpt-image-2；清晰度语义与文生图一致。
prompt	form field	是	对参考图的编辑/重绘要求。请写清楚要保留什么、改变什么、输出成什么风格。
image	file	是	单图参考时使用该字段上传主参考图。多图时也兼容重复传 image 字段。当前图片模型最多 8 张参考图且总大小不超过 40MB。
image[]	file	否	多图参考字段，可多次传入 image[]。当前图片模型最多 8 张参考图，总大小不超过 40MB。
mask	file	否	可选蒙版文件；平台会随 multipart 一起转发给上游，是否生效取决于模型。
n	form field	否	返回图片张数，默认 1；计费按张数累计。
size	form field	否	比例或尺寸，只支持下方尺寸白名单，例如 1:1、16:9、1024x1024、1536x1024、3840x2160。
quality / style / background	form field	否	与文生图含义一致，用于控制画质、风格和背景策略。
response_format	form field	否	支持 url / b64_json。API Key 同步调用默认 b64_json；如需图片链接请显式传 url。
output_format / upscale	form field	否	与文生图一致。gpt-image-2 的 2K / 4K 为放大输出；gpt-image-2-4K 高质量线路的 2K / 4K 会以原生高清尺寸参数请求上游。

图片尺寸白名单

比例	1K	2K	4K
1:1	1024x1024	2048x2048	2880x2880
3:2	1536x1024	2160x1440	3456x2304
2:3	1024x1536	1440x2160	2304x3456
16:9	1280x720	2560x1440	3840x2160
9:16	720x1280	1440x2560	2160x3840
4:3	1024x768	2048x1536	3200x2400
3:4	768x1024	1536x2048	2400x3200
21:9	1920x816	3120x1344	3840x1648

单参考图示例

curl -X POST "/api/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留产品主体和构图，把背景改成极简白色摄影棚，增强高端商业海报质感" \
  -F "image=@./reference.png" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "response_format=url"

多参考图示例

curl -X POST "/api/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=以第一张人物为主体，参考第二张的服装质感和第三张的背景氛围，生成电影海报风格" \
  -F "image[]=@./person.png" \
  -F "image[]=@./style.png" \
  -F "image[]=@./background.png" \
  -F "size=9:16" \
  -F "quality=high" \
  -F "response_format=url"

5. 返回格式与图片保存

response_format=url 会返回可访问的图片 URL。平台会尽量保持 OpenAI 兼容结构，并为生成结果补充站内保存后的 url、storageKey、mimeType、bytes 等字段，方便后续预览、下载和审计。

response_format=b64_json 会直接返回 data[].b64_json，适合 Cherry Studio、Chatbox 或不方便二次下载图片 URL 的工作流。API Key 同步调用未传 response_format 时也会默认按 b64_json 处理；站内在线生图会继续使用 URL 返回，以便更快展示和后台保存原图。

生成结果 URL 属于临时原图地址，仅保留 6 小时。超过有效期后再次访问会返回 HTTP 410 Gone 和“图片已过期”提示；如需长期保存，请在有效期内下载到自己的存储，或在站内加入“我的素材”。

URL 返回示例

{
  "created": 1710000000,
  "data": [
    {
      "url": "https://draw.hugusir.top/api/files/generated/xxx.png",
      "storageKey": "generated/xxx.png",
      "mimeType": "image/png",
      "bytes": 1234567
    }
  ]
}

b64_json 返回示例

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

图片过期响应

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "code": 1,
  "data": null,
  "msg": "图片已过期：生成图片仅保留 6 小时，请重新生成；保存到“我的素材”后可永久保留。"
}

使用 url 返回的是原图地址；平台不会压缩 API 生成结果，图片质量以模型实际输出为准。

6. 异步图片任务（推荐用于网站后端和长耗时场景）

图片生成可能耗时较长。如果你的业务会被浏览器、反向代理或 Cloudflare 长请求限制影响，推荐使用异步任务：先创建任务，立即获得 JOB_ID，再轮询状态。任务成功时 responseBody 是图片接口的原始兼容响应；失败时 errorMessage 返回可读错误。

示例请求

# 1) 创建异步文生图任务，适合网站后端、批量任务和长耗时场景
curl -X POST "/api/ai-jobs/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "极简高级感护肤品海报，柔和棚拍光，干净背景，广告级质感",
    "size": "3:2",
    "quality": "high",
    "upscale": "2k",
    "n": 1
  }'

# 2) 轮询任务状态，直到 status 为 success 或 failed
curl "/api/ai-jobs/JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

7. SDK 示例

大多数 OpenAI 兼容 SDK 都可以通过修改 base_url 接入。额外参数可放到 extra_body 中。

Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="/api/v1",
    api_key="YOUR_API_KEY",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="A cute orange cat playing with yarn, soft studio light, high detail",
    n=1,
    size="1:1",
    extra_body={
        "quality": "high",
        "style": "natural",
        "upscale": "2k",
        "response_format": "url",
    },
)
print(resp.data[0].url)

8. 常见错误说明

业务错误结构

{
  "code": 1,
  "data": null,
  "msg": "余额不足，无法完成本次 AI 请求"
}

未登录或权限不足：没有携带有效 API Key，或 Key 已停用/删除。
余额不足：当前账号积分不足，请先充值后重试。
缺少模型名称：请求体没有传 model，或图生图 multipart 里没有 model 字段。
请求内容过大：当前图片模型图生图最多 8 张参考图且总大小不超过 40MB。
尺寸或比例设置不正确：传入的 size 不在尺寸白名单内，请查看本页“图片尺寸白名单”后调整参数。
当前生图通道拥挤，请稍后再试：当前生图通道排队或上游响应较慢，请稍后重新提交；如持续出现，可联系 QQ群：668350542 协助排查。
暂未开放能力：当前对外 API 优先开放图片生成与图生图；文本/提示词优化 API、视频 API 会在能力稳定后再开放。

正在打开创作工具

HuGu Draw 正在准备画布、素材与工作台资源，请稍候。

HuGu API Docs

图片生成 API 接口文档

对外 API 目前开放图片能力：文生图和图生图。登录后可在 API Keys 页面创建密钥，再把下方 Base URL 接入到你的网站、软件或自动化工作流。

一块画布，完成从灵感到成图

管理 API Keys 充值积分

/api/v1

OpenAI Compatible Base URL

/api

异步任务 Base URL

gpt-image-2

主要模型

当前可用能力

文生图

图生图

OpenAI 兼容调用

gpt-image-2

本页优先展示当前可直接接入的图片 API；更多能力会在稳定开放后补充到文档。

1. 快速开始

Base URL：/api/v1

鉴权方式：推荐使用 Authorization: Bearer YOUR_API_KEY；也兼容 X-Api-Key / X-Access-Key 请求头。

创建密钥：登录后前往 /apikeys 创建 API Key。密钥通常以 ik_ 开头，明文只展示一次，请保存到你的服务端环境变量，不要放到前端源码里。

计费说明：请求成功后按模型单价 × n 扣除积分；上游失败或平台拒绝时会按站内规则退款/不扣费。

2. 模型与适用场景

gpt-image-2

3. 文生图：POST /images/generations

使用 JSON 请求体提交提示词。适合从零生成图片、海报、电商主图、角色设定、插画、封面和创意草图。

参数	类型	必填	说明
model	string	是	图片模型 ID，目前开放 gpt-image-2。gpt-image-2 为标准模型，2K / 4K 属于高清放大输出；gpt-image-2-4K 高质量线路为 gpt-image-2-4K 高质量线路，2K / 4K 会以原生高清尺寸参数提交给上游生成，不做本地插值、后期差分或二次放大。
prompt	string	是	生图提示词。建议写清主体、场景、构图、风格、光线、材质、色彩、文字限制和负面要求。
n	number	否	生成张数，默认 1。计费会按生成张数累计；对外调用建议一次 1 张，批量任务由业务侧排队。
size	string	否	比例或尺寸。只支持下方白名单中的 8 种比例和对应明确尺寸；未传或传入不支持尺寸时会按 1:1 安全归一。
quality	string	否	画质偏好，常用 high / medium / low，也兼容 standard。尺寸档位由 size + upscale 决定，quality 不单独决定输出尺寸。
style	string	否	风格倾向，常用 natural / vivid。natural 更自然克制，vivid 更鲜艳强烈。
background	string	否	背景策略，常用 opaque / transparent / auto。透明背景是否可用取决于模型与上游。
response_format	string	否	返回格式，支持 url / b64_json。API Key 同步调用默认 b64_json，以兼容 Cherry Studio；如需图片链接请显式传 url。
output_format	string	否	输出文件格式扩展字段，常用 png / jpeg / webp；平台会透传给上游，实际支持以模型为准。
upscale	string	否	清晰度档位。留空为 1K；可传 2k / 4k。使用 gpt-image-2 时代表高清放大；使用 gpt-image-2-4K 高质量线路时会以对应原生高清尺寸参数请求上游，实际像素随宽高比变化。

图片尺寸白名单

比例	1K	2K	4K
1:1	1024x1024	2048x2048	2880x2880
3:2	1536x1024	2160x1440	3456x2304
2:3	1024x1536	1440x2160	2304x3456
16:9	1280x720	2560x1440	3840x2160
9:16	720x1280	1440x2560	2160x3840
4:3	1024x768	2048x1536	3200x2400
3:4	768x1024	1536x2048	2400x3200
21:9	1920x816	3120x1344	3840x1648

返回 URL 示例

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A realistic sunset cityscape, wet street reflections, cinematic lighting, dense midground details, clean composition",
    "n": 1,
    "size": "16:9",
    "quality": "high",
    "style": "natural",
    "background": "opaque",
    "response_format": "url"
  }'

返回 b64_json 示例（Cherry Studio / Chatbox）

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute orange cat playing with yarn, clean studio lighting",
    "n": 1,
    "size": "1:1",
    "quality": "high",
    "response_format": "b64_json"
  }'

标准模型放大 4K 示例

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean premium product poster, soft commercial lighting, crisp details, minimal beige background",
    "size": "1:1",
    "quality": "high",
    "response_format": "url",
    "output_format": "png",
    "upscale": "4k"
  }'

4K 高质量线路示例

curl -X POST "/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-4K 高质量线路",
    "prompt": "A premium commercial poster, ultra sharp product details, polished studio lighting, clean luxury background",
    "n": 1,
    "size": "1:1",
    "quality": "high",
    "upscale": "4k",
    "response_format": "url"
  }'

4. 图生图：POST /images/edits

参数	类型	必填	说明
model	form field	是	图片模型 ID，目前开放 gpt-image-2；清晰度语义与文生图一致。
prompt	form field	是	对参考图的编辑/重绘要求。请写清楚要保留什么、改变什么、输出成什么风格。
image	file	是	单图参考时使用该字段上传主参考图。多图时也兼容重复传 image 字段。当前图片模型最多 8 张参考图且总大小不超过 40MB。
image[]	file	否	多图参考字段，可多次传入 image[]。当前图片模型最多 8 张参考图，总大小不超过 40MB。
mask	file	否	可选蒙版文件；平台会随 multipart 一起转发给上游，是否生效取决于模型。
n	form field	否	返回图片张数，默认 1；计费按张数累计。
size	form field	否	比例或尺寸，只支持下方尺寸白名单，例如 1:1、16:9、1024x1024、1536x1024、3840x2160。
quality / style / background	form field	否	与文生图含义一致，用于控制画质、风格和背景策略。
response_format	form field	否	支持 url / b64_json。API Key 同步调用默认 b64_json；如需图片链接请显式传 url。
output_format / upscale	form field	否	与文生图一致。gpt-image-2 的 2K / 4K 为放大输出；gpt-image-2-4K 高质量线路的 2K / 4K 会以原生高清尺寸参数请求上游。

图片尺寸白名单

比例	1K	2K	4K
1:1	1024x1024	2048x2048	2880x2880
3:2	1536x1024	2160x1440	3456x2304
2:3	1024x1536	1440x2160	2304x3456
16:9	1280x720	2560x1440	3840x2160
9:16	720x1280	1440x2560	2160x3840
4:3	1024x768	2048x1536	3200x2400
3:4	768x1024	1536x2048	2400x3200
21:9	1920x816	3120x1344	3840x1648

单参考图示例

curl -X POST "/api/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留产品主体和构图，把背景改成极简白色摄影棚，增强高端商业海报质感" \
  -F "image=@./reference.png" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "response_format=url"

多参考图示例

curl -X POST "/api/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=以第一张人物为主体，参考第二张的服装质感和第三张的背景氛围，生成电影海报风格" \
  -F "image[]=@./person.png" \
  -F "image[]=@./style.png" \
  -F "image[]=@./background.png" \
  -F "size=9:16" \
  -F "quality=high" \
  -F "response_format=url"

5. 返回格式与图片保存

URL 返回示例

{
  "created": 1710000000,
  "data": [
    {
      "url": "https://draw.hugusir.top/api/files/generated/xxx.png",
      "storageKey": "generated/xxx.png",
      "mimeType": "image/png",
      "bytes": 1234567
    }
  ]
}

b64_json 返回示例

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

图片过期响应

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "code": 1,
  "data": null,
  "msg": "图片已过期：生成图片仅保留 6 小时，请重新生成；保存到“我的素材”后可永久保留。"
}

使用 url 返回的是原图地址；平台不会压缩 API 生成结果，图片质量以模型实际输出为准。

6. 异步图片任务（推荐用于网站后端和长耗时场景）

示例请求

# 1) 创建异步文生图任务，适合网站后端、批量任务和长耗时场景
curl -X POST "/api/ai-jobs/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "极简高级感护肤品海报，柔和棚拍光，干净背景，广告级质感",
    "size": "3:2",
    "quality": "high",
    "upscale": "2k",
    "n": 1
  }'

# 2) 轮询任务状态，直到 status 为 success 或 failed
curl "/api/ai-jobs/JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

7. SDK 示例

大多数 OpenAI 兼容 SDK 都可以通过修改 base_url 接入。额外参数可放到 extra_body 中。

Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="/api/v1",
    api_key="YOUR_API_KEY",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="A cute orange cat playing with yarn, soft studio light, high detail",
    n=1,
    size="1:1",
    extra_body={
        "quality": "high",
        "style": "natural",
        "upscale": "2k",
        "response_format": "url",
    },
)
print(resp.data[0].url)

8. 常见错误说明

业务错误结构

{
  "code": 1,
  "data": null,
  "msg": "余额不足，无法完成本次 AI 请求"
}

未登录或权限不足：没有携带有效 API Key，或 Key 已停用/删除。
余额不足：当前账号积分不足，请先充值后重试。
缺少模型名称：请求体没有传 model，或图生图 multipart 里没有 model 字段。
请求内容过大：当前图片模型图生图最多 8 张参考图且总大小不超过 40MB。
尺寸或比例设置不正确：传入的 size 不在尺寸白名单内，请查看本页“图片尺寸白名单”后调整参数。
当前生图通道拥挤，请稍后再试：当前生图通道排队或上游响应较慢，请稍后重新提交；如持续出现，可联系 QQ群：668350542 协助排查。
暂未开放能力：当前对外 API 优先开放图片生成与图生图；文本/提示词优化 API、视频 API 会在能力稳定后再开放。