GenCraft.ccGenCraft.cc

API 文档

POST /api/v1/generate · GET /api/v1/tasks

面向批量调用与 agent 集成的公开接口。直接用你账户已有的 API Key 鉴权，无需单独申请 token。

鉴权

在 HTTP header 里附带你的 API Key。这个 key 就是 GenCraft 在你购买套餐后为你账户分配、存在 user_keys 表里的 api_key。校验失败返回 401。

HEADER
Authorization: Bearer <your_api_key>
401 RESPONSE
{ "error": { "type": "invalid_api_key", "message": "Invalid API key" } }
POST/api/v1/generate

创建图像生成任务

把任务提交给上游后立即返回 task_ids。拿到 task_ids 后有两种方式拿结果：(A) 自己用 GET /v1/tasks/{id} 轮询；(B) 直接登录网站——同账号的「图像创作」tab 会自动接管这些任务，完成后落到「我的作品」里。

请求

curl -X POST https://www.gencraft.cc/api/v1/generate \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene Japanese garden in autumn",
    "model": "flash",
    "mode": "text",
    "aspect": "16:9",
    "imageSize": "2K",
    "count": 1
  }'

响应

{
  "task_ids": ["task_abc123"],
  "email": "you@example.com"
}

Body 参数

字段类型必填默认说明
promptstring✓—生成提示词
modelstringgpt-image-2模型 id（见下表）
modetext | edit | fusiontexttext=文生图；edit=单图编辑；fusion=多图融合
aspectstring1:1比例：1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9 等
imageSize1K | 2K | 4K2K输出分辨率
countnumber1生成张数（受模型上限约束）
imageUrlsstring[][]edit / fusion 模式的参考图 URL

可用模型

model名称支持模式
gpt-image-2GPT Image 2text, edit
proNano Banana Protext, edit
flash2Nano Banana 2text, edit
flashNano Bananatext, edit

错误码

HTTPerror.type触发条件
400invalid_requestbody 不是 JSON / prompt 为空 / model 不存在 / model 不支持该 mode
401unauthorized缺 Authorization header 或不是 Bearer 格式
401invalid_api_keyAPI key 在 user_keys 表里查不到
500upstream_error上游图像服务调用失败（包含上游返回的 message）
GET/api/v1/tasks/{task_id}

轮询单个任务

返回上游任务状态。status 取值：queued / in_progress / completed / failed。completed 时多 imageUrl 字段；failed 时多 error 字段。

请求

curl https://www.gencraft.cc/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer <your_api_key>"

响应

{
  "task_id": "task_abc123",
  "status": "completed",
  "progress": 100,
  "imageUrl": "https://files.example.com/generated/xxx.png"
}
GET/api/v1/tasks?ids=t1,t2

批量轮询任务

一次请求查多个任务，省 N 次 HTTP 往返与鉴权。返回顺序与入参 ids 严格对应。最多一次 20 个 id。

请求

curl "https://www.gencraft.cc/api/v1/tasks?ids=task_abc,task_def,task_ghi" \
  -H "Authorization: Bearer <your_api_key>"

响应

{
  "tasks": [
    { "task_id": "task_abc", "status": "completed", "progress": 100, "imageUrl": "https://..." },
    { "task_id": "task_def", "status": "in_progress", "progress": 60 },
    { "task_id": "task_ghi", "status": "failed", "progress": 0, "error": "model overloaded" }
  ]
}

查询接口错误码

HTTPerror.type触发条件
400invalid_request缺 ids 参数，或 ids 超过 20 个
401unauthorized缺 Authorization header 或不是 Bearer 格式
401invalid_api_keyAPI key 在 user_keys 表里查不到
POST/api/v1/upload

上传参考图（用于 edit / fusion）

服务端从 source_url 下载图片后转发到上游 CDN，返回稳定 URL。把返回的 URL 放进 generate_image 的 imageUrls 字段即可。每张最大 25 MB；接受 png / jpeg / webp / gif / bmp。

请求

curl -X POST https://www.gencraft.cc/api/v1/upload \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://example.com/cat.png"}'

响应

{
  "url": "https://files.example.com/uploads/abc123.png",
  "filename": "cat.png",
  "content_type": "image/png",
  "bytes": 524288
}
GET/api/v1/history?page=1&limit=20

查询账号生成历史

返回该 API key 所属账号的过往生成记录，按时间倒序。分页参数：page（1-indexed）、limit（最大 50）。

请求

curl "https://www.gencraft.cc/api/v1/history?page=1&limit=20" \
  -H "Authorization: Bearer <your_api_key>"

响应

{
  "items": [
    {
      "id": "tsk_img_xxx",
      "prompt": "a cat in autumn",
      "model": "flash",
      "mode": "text",
      "aspect": "16:9",
      "imageSize": "2K",
      "imageCount": 1,
      "images": ["https://..."],
      "refs": [],
      "createdAt": 1777461252000
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}
GET/api/v1/user/status

查询账号档位

返回邮箱、套餐档位（trial / starter / standard / pro）、以及上游 key 是否配置。agent 可据此决定是否上高消耗模型。

请求

curl https://www.gencraft.cc/api/v1/user/status \
  -H "Authorization: Bearer <your_api_key>"

响应

{
  "email": "you@example.com",
  "tier": "pro",
  "has_key": true
}

通过 MCP 使用（Claude Desktop / Cursor / Cline）

对 LLM agent 来说，接入 GenCraft 最简单的方式是用官方 MCP server——已发布到 npm：@gencraft/mcp-server。它通过 stdio 暴露 6 个 tool（generate_image、get_task、batch_get_tasks、upload_reference_image、list_my_generations、get_account_status），所有 MCP 兼容客户端开箱即用。在你客户端的 MCP 配置里加下面这段就行。

npm · @gencraft/mcp-server完整 README 与 Cursor / Cline 配置 →

Claude Desktop 配置

路径：~/Library/Application Support/Claude/claude_desktop_config.json（macOS） · %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "gencraft": {
      "command": "npx",
      "args": ["-y", "@gencraft/mcp-server"],
      "env": {
        "GENCRAFT_API_KEY": "<your_api_key>"
      }
    }
  }
}

注意事项

  • •调用结果会自动归到该 API Key 所属的账户：任务先写入 pending_tasks；该账户下次登录网站打开「图像创作」tab，前端会自动接管轮询，完成后落到 generations / generation_images 表，出现在「我的作品」与「资产库」里。如需纯 fire-and-forget 不在网页里展示，请使用专门的「调用方」账号。
  • •服务端不做限流，你的上游额度即天然配额。
  • •轮询频率建议 2-5 秒一次；批量接口最多一次 20 个 id。
  • •不要把 API Key 放进前端代码。仅在你自己的后端使用。
© 2026 GenCraft.cc. All rights reserved.