DrawNew.comAPI 文档
POST /api/v1/generate · GET /api/v1/tasks
面向批量调用与 agent 集成的公开接口。直接用你账户已有的 API Key 鉴权，无需单独申请 token。
/api/v1/generate创建图像生成任务
把任务提交给上游后立即返回 task_ids。拿到 task_ids 后有两种方式拿结果：(A) 自己用 GET /v1/tasks/:id 轮询；(B) 直接登录网站——同账号的「图像创作」tab 会自动接管这些任务，完成后落到「我的作品」里。
请求
curl -X POST https://www.drawnew.com/api/v1/generate \
-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"]
}Body 参数
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| prompt | string | ✓ | — | 生成提示词 |
| model | string | gpt-image-2 | 模型 id（见下表） | |
| mode | text | edit | fusion | text | text=文生图；edit=单图编辑；fusion=多图融合 | |
| aspect | string | 1:1 | 比例：1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9 等 | |
| imageSize | 1K | 2K | 4K | 2K | 输出分辨率 | |
| count | number | 1 | 生成张数（受模型上限约束） | |
| imageUrls | string[] | [] | edit / fusion 模式的参考图 URL |
可用模型
| model | 名称 | 支持模式 |
|---|---|---|
| gpt-image-2 | GPT Image 2 | text, edit |
| pro | Nano Banana Pro | text, edit |
| flash2 | Nano Banana 2 | text, edit |
| flash | Nano Banana | text, edit |
错误码
| HTTP | error.type | 触发条件 |
|---|---|---|
| 400 | invalid_request | body 不是 JSON / prompt 为空 / model 不存在 / model 不支持该 mode |
| 401 | unauthorized | 缺 Authorization header 或不是 Bearer 格式 |
| 401 | invalid_api_key | API key 在 user_keys 表里查不到 |
| 403 | no_credits | 月度额度耗尽，请升级套餐 https://drawnew.com/pricing |
/api/v1/tasks/{task_id}轮询单个任务
返回上游任务状态。status 取值：queued / in_progress / completed / failed。completed 时多 imageUrl 字段；failed 时多 error 字段。
请求
curl https://www.drawnew.com/api/v1/tasks/task_abc123响应
{
"task_id": "task_abc123",
"status": "completed",
"progress": 100,
"imageUrl": "https://files.example.com/generated/xxx.png"
}/api/v1/tasks?ids=t1,t2批量轮询任务
一次请求查多个任务，省 N 次 HTTP 往返与鉴权。返回顺序与入参 ids 严格对应。最多一次 20 个 id。
请求
curl "https://www.drawnew.com/api/v1/tasks?ids=task_abc,task_def,task_ghi"响应
{
"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" }
]
}查询接口错误码
| HTTP | error.type | 触发条件 |
|---|---|---|
| 400 | invalid_request | 缺 ids 参数，或 ids 超过 20 个 |
| 401 | unauthorized | 缺 Authorization header 或不是 Bearer 格式 |
| 401 | invalid_api_key | API key 在 user_keys 表里查不到 |
/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.drawnew.com/api/v1/upload \
-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
}通过 MCP 使用（Claude Desktop / Cursor / Cline）
对 LLM agent 来说，接入 DrawNew 最简单的方式是用官方 MCP server——已发布到 npm：@drawnew/mcp-server。它通过 stdio 暴露 6 个 tool（generate_image、get_task、batch_get_tasks、upload_reference_image、list_my_generations、get_account_status），所有 MCP 兼容客户端开箱即用。在你客户端的 MCP 配置里加下面这段就行。
Claude Desktop 配置
路径：~/Library/Application Support/Claude/claude_desktop_config.json（macOS） · %APPDATA%\Claude\claude_desktop_config.json（Windows）
{
"mcpServers": {
"drawnew": {
"command": "npx",
"args": ["-y", "@drawnew/mcp-server"]
}
}
}注意事项
- •调用结果会自动归到该 API Key 所属的账户：任务先写入 pending_tasks；该账户下次登录网站打开「图像创作」tab，前端会自动接管轮询，完成后落到 generations / generation_images 表，出现在「我的作品」与「资产库」里。如需纯 fire-and-forget 不在网页里展示，请使用专门的「调用方」账号。
- •服务端有积分检查——月度额度耗尽后 API 返回 HTTP 403，error.type=no_credits。
- •轮询频率建议 2-5 秒一次；批量接口最多一次 20 个 id。
- •不要把 API Key 放进前端代码。仅在你自己的后端使用。