Skip to content
PuzzleGenio - 免费拼图制作工具
PuzzleGenio

谜题 REST API 参考

使用 Bearer API 密钥。创建操作将完整结果保存到“我的谜题”，并返回浏览器页面链接，而非文件内容。

API 密钥

身份验证

发送 Authorization: Bearer YOUR_API_KEY。外部接口不接受 Cookie。请将密钥保存在服务器端。

额度与分享

请求示例

curl -X POST https://puzzlegenio.com/api/v1/puzzles \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: task-000000000001' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "wordsearch", "preset": "word-search-for-kids", "title": "Animal word search", "input": { "words": [ "CAT", "DOG", "LION", "TIGER" ] }, "options": { "gridSize": 10, "allowDiagonal": false } }'

创建成功的响应示例

{
  "data": {
    "savedId": "123456789",
    "shareId": "AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "type": "wordsearch",
    "preset": "word-search-for-kids",
    "viewUrl": "https://puzzlegenio.com/puzzles/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "exportPageUrl": "https://puzzlegenio.com/puzzles/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "editUrl": "https://puzzlegenio.com/word-search-for-kids?id=123456789",
    "playUrl": "https://puzzlegenio.com/word-search-maker/play/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "expiresAt": "2026-11-01T00:00:00.000Z",
    "shareState": "active",
    "savedCount": 1,
    "limit": 20,
    "formats": [
      "pdf",
      "answer-pdf"
    ],
    "itemCount": 1,
    "warnings": []
  },
  "requestId": "00000000-0000-4000-8000-000000000000"
}

示例中的编号和日期仅说明响应结构。data 包含已保存结果；requestId 标识本次请求。

viewUrl
公开预览页；持有链接的人也可查看答案。
exportPageUrl
在浏览器中选择下载格式的页面。它可与 viewUrl 相同，并非文件直链。
editUrl
仅限所有者的编辑页；必须登录并验证所有权。
playUrl
仅在支持的模式下提供游戏页；否则为 null。

REST 接口

POST/api/v1/puzzles
GET/api/v1/puzzles
GET/api/v1/puzzles/{savedId}
DELETE/api/v1/puzzles/{savedId}
POST/api/v1/puzzles/{savedId}/share
GET/api/v1/capabilities
GET/api/v1/results/{shareId}
POST/api/v1/assets
POST/api/v1/assets/import
GET/api/v1/openapi.json

机器可读的 OpenAPI 结构

幂等与响应

创建时必须提供 Idempotency-Key。使用同一密钥和请求体重试会得到同一已保存谜题。密钥相同但请求体不同返回 409。首次创建返回 201，重放返回 200。

错误处理

错误结构为 {error:{code,message,details},requestId}。400 表示 JSON 或请求键错误，401 为认证失败，403 为额度或权益不足，404 为未知或无权访问，409 为密钥冲突，410 为分享失效，413 为体积超限，415 为媒体类型错误，422 为参数或生成失败，429 为限流并附 Retry-After，503 为创建暂不可用。

谜题 REST API 参考