跃码
登录免费注册
注册免费账号获取 API 密钥，立即开始调用。登录后可在此页面测试接口。

公开 API 文档

三步接入：注册获取密钥 → 调用创建接口 → 调用换址接口。认证通过 X-API-Key 请求头完成。

curl -X POST /api/v1/codes \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

交互式测试

核心参数

字段说明约束
name活码名称1-80 字符
target_url目标 URLHTTP/HTTPS，创建和换址均做安全检测
slug短链标识可选，4-24 位字母数字连字符
group_name分组名称可选，用于控制台筛选
tags标签数组可选，用于检索和归类

查询参数

字段说明约束
limit分页数量活码列表默认 50、最大 500；扫码明细默认 100、最大 500
offset分页偏移量默认 0；负数按 0 处理
format导出格式扫码明细支持 csv/xlsx；二维码图片支持 svg

状态与限制

认证X-API-Key
免费配额500 次/日
超限HTTP 429
二维码PNG / SVG
方法路径说明
POST/api/v1/codes创建活码
GET/api/v1/codes查询活码列表
GET/api/v1/codes/{id}查询活码详情
PUT/api/v1/codes/{id}更新活码
PATCH/api/v1/codes/{id}/target-url更换目标 URL
POST/api/v1/codes/{id}/pause暂停活码
POST/api/v1/codes/{id}/resume恢复活码
DELETE/api/v1/codes/{id}归档活码
GET/api/v1/codes/{id}/stats获取统计
GET/api/v1/codes/{id}/scans获取扫码明细
POST/api/v1/codes/batch批量创建
PATCH/api/v1/codes/batch/target-url批量换址
GET/api/v1/codes/{id}/qrcode获取二维码图片

POST /api/v1/codes

创建活码

请求

curl -X POST /api/v1/codes \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("POST", "/api/v1/codes",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

GET /api/v1/codes

查询活码列表

请求

curl -X GET /api/v1/codes \
  -H "X-API-Key: yq_xxx"

Python

import requests
r = requests.request("GET", "/api/v1/codes",
  headers={"X-API-Key": "yq_xxx"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

GET /api/v1/codes/{id}

查询活码详情

请求

curl -X GET /api/v1/codes/{id} \
  -H "X-API-Key: yq_xxx"

Python

import requests
r = requests.request("GET", "/api/v1/codes/{id}",
  headers={"X-API-Key": "yq_xxx"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

PUT /api/v1/codes/{id}

更新活码

请求

curl -X PUT /api/v1/codes/{id} \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("PUT", "/api/v1/codes/{id}",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

PATCH /api/v1/codes/{id}/target-url

更换目标 URL

请求

curl -X PATCH /api/v1/codes/{id}/target-url \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("PATCH", "/api/v1/codes/{id}/target-url",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

POST /api/v1/codes/{id}/pause

暂停活码

请求

curl -X POST /api/v1/codes/{id}/pause \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("POST", "/api/v1/codes/{id}/pause",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

POST /api/v1/codes/{id}/resume

恢复活码

请求

curl -X POST /api/v1/codes/{id}/resume \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("POST", "/api/v1/codes/{id}/resume",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

DELETE /api/v1/codes/{id}

归档活码

请求

curl -X DELETE /api/v1/codes/{id} \
  -H "X-API-Key: yq_xxx"

Python

import requests
r = requests.request("DELETE", "/api/v1/codes/{id}",
  headers={"X-API-Key": "yq_xxx"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

GET /api/v1/codes/{id}/stats

获取统计

请求

curl -X GET /api/v1/codes/{id}/stats \
  -H "X-API-Key: yq_xxx"

Python

import requests
r = requests.request("GET", "/api/v1/codes/{id}/stats",
  headers={"X-API-Key": "yq_xxx"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

GET /api/v1/codes/{id}/scans

获取扫码明细

请求

curl -X GET /api/v1/codes/{id}/scans \
  -H "X-API-Key: yq_xxx"

Python

import requests
r = requests.request("GET", "/api/v1/codes/{id}/scans",
  headers={"X-API-Key": "yq_xxx"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

POST /api/v1/codes/batch

批量创建

请求

curl -X POST /api/v1/codes/batch \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("POST", "/api/v1/codes/batch",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

PATCH /api/v1/codes/batch/target-url

批量换址

请求

curl -X PATCH /api/v1/codes/batch/target-url \
  -H "X-API-Key: yq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"菜单","target_url":"https://example.com/menu"}'

Python

import requests
r = requests.request("PATCH", "/api/v1/codes/batch/target-url",
  headers={"X-API-Key": "yq_xxx"},
  json={"name": "菜单", "target_url": "https://example.com/menu"})
print(r.status_code, r.text)

响应

{"code":{"id":1,"slug":"abc123","short_url":"https://qr.example/s/abc123"}}

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

GET /api/v1/codes/{id}/qrcode

获取二维码图片

请求

curl -X GET /api/v1/codes/{id}/qrcode \
  -H "X-API-Key: yq_xxx"

Python

import requests
r = requests.request("GET", "/api/v1/codes/{id}/qrcode",
  headers={"X-API-Key": "yq_xxx"})
print(r.status_code, r.text)

响应

image/png 或 image/svg+xml

常见错误

API_KEY_REQUIRED / API_KEY_INVALID / BAD_JSON / BODY_TOO_LARGE / RATE_LIMITED / INVALID_URL / URL_BLOCKED / CODE_QUOTA_EXCEEDED / NOT_FOUND

频率限制

免费版 500 次/日，超限返回 HTTP 429，响应头包含 Retry-After。

错误码

API_KEY_REQUIRED缺少 X-API-Key 请求头
API_KEY_INVALID密钥无效、停用或已删除
BAD_JSON请求体不是有效的单个 JSON 对象
BODY_TOO_LARGEJSON 请求体超过 2MB
RATE_LIMITEDAPI 日调用次数达到账号配额
INVALID_URL目标 URL 格式或协议不符合要求
URL_BLOCKED目标 URL 被安全策略拦截
CODE_QUOTA_EXCEEDED活码数量已达到账号配额
NOT_FOUND资源不存在或不属于当前账号
CAPTCHA_REQUIRED人机验证缺失、过期或校验失败
TEMP_DAILY_LIMITED同一 IP 首页临时活码体验次数已用完
LEAD_RATE_LIMITED公开线索表单提交过于频繁
REGISTER_RATE_LIMITED同一 IP 注册请求过于频繁
VERIFICATION_RATE_LIMITED验证邮件请求过于频繁
PASSWORD_RESET_RATE_LIMITED密码重置请求过于频繁
REPORT_RATE_LIMITED同一 IP 举报提交过于频繁