API 文档

通过 REST API 把 SenseForm 接到你的服务里。公开接口使用 API Key；创建 Key 需要先登录网站。

OpenAPI YAML 在设置页签发 Key

POST/api/v1/generations202 · API Key

排队生成一张设计图。立即返回 job id，不要同步等待出图。

GET/api/v1/jobs/:id200 · API Key

查询该 Key 所属用户的任务。他人任务返回 404。

GET/api/v1/styles200 · API Key

已发布风格列表，字段与网站 /styles 同源。

POST/api/v1/keys201 · 登录会话

签发 API Key。明文 sf_live_... 只返回一次，库中仅存 sha256。

鉴权

生成 / 任务 / 风格接口：Authorization: Bearer sf_live_...

签发与作废 Key：必须带网站登录 Cookie，不能用 API Key 调 /api/v1/keys。

无效 Key 返回 401；积分不足返回 402；别人的任务返回 404。

任务成功后的 output_urls 是站内图片代理的绝对地址（不是裸的 Vercel private blob）。签名链接约 10 分钟内可直接 GET；过期后重新查询任务，或在 GET 代理时带上同一把 API Key。

任务成功后会写入该用户的 projects 行（与 /create 相同），可在网站「我的项目」里看到这张图。

积分与会员配额与 /create 相同：1K=10，2K=20，4K=30，4K Pro=40。模型密钥只存在服务端环境变量。

curl 示例

curl -sS -X POST https://www.senseform.net/api/v1/keys \
  -H "Content-Type: application/json" \
  --cookie "YOUR_SESSION_COOKIE" \
  -d '{"name":"mcp"}'

curl -sS -X POST https://www.senseform.net/api/v1/generations \
  -H "Authorization: Bearer sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "春季新品发布会",
    "copy": "限时开放报名",
    "material": "poster",
    "aspect_ratio": "3:4",
    "quality": "2k",
    "model": "nano-banana",
    "style_id": "YOUR_STYLE_UUID"
  }'

curl -sS https://www.senseform.net/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sf_live_..."

OUTPUT_URL=$(curl -sS https://www.senseform.net/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sf_live_..." | jq -r '.output_urls[0]')
curl -sS -D - -o result.jpg "$OUTPUT_URL"
# Expect HTTP 200 and content-type image/jpeg or image/png.
# Signed proxy URLs expire in ~10 minutes; poll GET /jobs/:id again, or:
curl -sS -D - -o result.jpg "$OUTPUT_URL" \
  -H "Authorization: Bearer sf_live_..."

请求体字段

POST /api/v1/generations

title 必填，映射为生成主题。
copy 可选主文案。
material poster / flyer / long / banner / landing / standee / backdrop / social / invite / card。
aspect_ratio 如 3:4、16:9；缺省按素材类型。
quality 1k | 2k | 4k | 4k_pro。
model nano-banana | gemini | gpt-image-2（gemini 与 nano-banana 同走 Gemini）。
style_id 建议传入；缺省使用第一个已发布风格。
use_brand 使用该用户默认品牌规范。
product_image_urls 最多 5 张产品图 URL。

本版本不包含 MCP 包装、套装/对话/品牌 CRUD。完整 schema 见 OpenAPI 。