OPEN API

API Access

Bring Edson Shop image generation into your agents and automation: Claude Code, Cursor, scripts, and n8n can all call it directly.

API Keys

The plaintext is shown only once at creation/rotation; rotating invalidates the old key immediately.

Credits

API calls share the same credit balance as the web app — pay per call, auto-refunded on failure.

Buy credits Usage records

Quick Start

Three steps: create a key → copy the example → swap in your key and run.

Create an API key

# 1) 创建密钥后，直接上传商品图（--file 换成你的本地图片路径）
curl -X POST https://www.edsonshop.com/api/v1/agent/v1/files \
  -H "Authorization: Bearer edson_sk_..." \
  -F "file=@product.jpg"

Upload a product image to get a file_id

# 2) 智能抠图（透明底 PNG，mode=sync 默认挂起至完成）
curl -X POST https://www.edsonshop.com/api/v1/agent/v1/images/cutout \
  -H "Authorization: Bearer edson_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"file_ids": ["file_xxx"], "model": "gpt-image-2"}'

Run a cutout and fetch the result

# 3) 异步模式：提交后轮询，结果 URL 1 小时内有效
curl -X POST https://www.edsonshop.com/api/v1/agent/v1/images/edits \
  -H "Authorization: Bearer edson_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "白底电商主图，突出商品", "model": "gpt-image-2", "image_urls": ["https://.../product.jpg"], "mode": "async"}'

curl https://www.edsonshop.com/api/v1/agent/v1/tasks/agt_xxx \
  -H "Authorization: Bearer edson_sk_..."

Replace edson_sk_... with the key you created above.

Capabilities

v1 exposes four atomic capabilities; multi-step workflows (product kits, etc.) are composed by your scripts.

AI Cutout

Remove the background and return a transparent PNG — portraits and products, hair-level edges.

Text to Image

Generate images from a prompt with size options (up to 4 per call).

Image Edit

Restyle / retouch with reference images; accepts file_ids or image_urls.

E-commerce Workflows

Product kits and clone workflows: loop the atomic endpoints from your scripts.

Endpoint Reference

All endpoints live under /api/v1/agent/v1, authenticated via Authorization: Bearer edson_sk_...

Method	Endpoint	Description
POST	/agent/v1/files	Upload an image, returns file_id
POST	/agent/v1/images/generations	Text to image (sync by default / async polling)
POST	/agent/v1/images/edits	Image edit with file_ids or image_urls
POST	/agent/v1/images/cutout	AI cutout to transparent PNG
GET	/agent/v1/tasks/{task_id}	Task status and results (signed URLs valid for 1 hour)
GET	/agent/v1/models	Available models and pricing
GET	/agent/v1/account	Balance and usage summary
GET	/agent/v1/usage	Usage records (paged)

Common Errors

Code	Meaning
auth.invalid_api_key	Invalid key (missing / revoked / rotated / expired)
billing.insufficient_funds	Insufficient credits (HTTP 402, top up and retry)
agent.model_not_allowed	Model not in the whitelist (admin: agent_api.allowed_models)
agent.invalid_image_url	Failed to fetch the image URL
agent.content_blocked	Blocked by content moderation