DrawNew.comDrawNew.com

API 文件

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

面向批次呼叫與 agent 整合的公開介面。直接用你帳戶已有的 API Key 鑑權，無需單獨申請 token。

鑑權

在 HTTP header 裡附帶你的 API Key。這個 key 就是 DrawNew 在你購買方案後為你帳戶分配、存在 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.drawnew.com/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 表裡查不到
403no_credits月度額度耗盡，請升級套餐 https://drawnew.com/pricing
GET/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 \
  -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.drawnew.com/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.drawnew.com/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.drawnew.com/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.drawnew.com/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 來說，接入 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 配置裡加下面這段就行。

npm · @drawnew/mcp-server完整 README 與 Cursor / Cline 配置 →

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"],
      "env": {
        "DRAWNEW_API_KEY": "<your_api_key>"
      }
    }
  }
}

注意事項

  • •呼叫結果會自動歸到該 API Key 所屬的帳戶：任務先寫入 pending_tasks；該帳戶下次登入網站打開「圖像創作」tab，前端會自動接管輪詢，完成後落到 generations / generation_images 表，出現在「我的作品」與「資產庫」裡。如需純 fire-and-forget 不在網頁裡展示，請使用專門的「呼叫端」帳戶。
  • •服務端有積分檢查——月度額度耗盡後 API 返回 HTTP 403，error.type=no_credits。
  • •輪詢頻率建議 2-5 秒一次；批次介面最多一次 20 個 id。
  • •不要把 API Key 放進前端程式碼。僅在你自己的後端使用。
© 2026 DrawNew.com. All rights reserved.