跳到主要内容

获取图片验证码

POST 
/auth/v1/captcha/data

接口说明​

获取图片验证码接口，返回符合RFC 2397标准的内联图片数据URI，用于在登录、注册等场景中进行人机验证。

入参要求​

请求参数​

  • 无需传入参数，直接调用即可

前置条件​

  • 无特殊前置条件
  • 建议在用户登录失败次数过多时调用
  • 可在注册、找回密码等敏感操作时使用

出参说明​

成功响应​

  • data: 图片数据（必填，RFC 2397标准的内联图片数据URI，格式为data:image/gif;base64,xxx）
  • type: 资源类型（必填，固定值为"image"）
  • token: 验证码token（必填，用于后续验证接口）
  • expires_in: 过期时间（必填，单位为秒，默认300秒）

请求示例​

获取图片验证码请求示例​

POST /auth/v1/captcha/data
Content-Type: application/json

{}

响应示例​

获取成功响应示例​

{
  "data": "data:image/gif;base64,R0lGODlhyAAyAIcAAAAAAAAARAAAiAAAzABEAABERABEiABEzACIAACIRACIiACIzADMAADMRADMiADMzADd3REREQAAVQAAmQAA3QBVAABVVQBMmQBJ3QCZAACZTACZmQCT3QDdAADdSQDdkwDungDu7iIiIgAAZgAAqgAA7gBmAABmZgBVqgBP7gCqAACqVQCqqgCe7gDuAADuTwD/VQD/qgD//zMzMwAAdwAAuwAA/wB3AAB3dwBduwBV/wC7AAC7XQC7uwCq/wD/AEQAREQAiEQAzEREAEREREREiEREzESIAESIRESIiESIzETMAETMRETMiETMzEQAAFUAAFUAVUwAmUkA3VVVAFVVVUxMmUlJ3UyZAEyZTEyZmUmT3UndAEndSUndk0nd3U/u7mYAAGYAZlUAqk8A7mZmAGZmZlVVqk9P7lWqAFWqVVWqqk+e7k/uAE/uT0/unlX/qlX//3cAAHcAd10Au1UA/3d3AHd3d11du1VV/127AF27XV27u1Wq/1X/AFX/VYgAiIgAzIhEAIhERIhEiIhEzIiIAIiIRIiIiIiIzIjMAIjMRIjMiIjMzIgAAIgARJkATJkAmZMA3ZlMAJlMTJlMmZNJ3ZmZAJmZTJmZmZOT3ZPdAJPdSZPdk5Pd3ZkAAKoAAKoAVaoAqp4A7qpVAKpVVapVqp5P7qqqAKqqVaqqqp6e7p7uAJ7uT57unp7u7qr//7sAALsAXbsAu6oA/7tdALtdXbtdu6pV/7u7ALu7Xbu7u6qq/6r/AKr/Var/qswAzMxEAMxERMxEiMxEzMyIAMyIRMyIiMyIzMzMAMzMRMzMiMzMzMwAAMwARMwAiN0Ak90A3d1JAN1JSd1Jk91J3d2TAN2TSd2Tk92T3d3dAN3dSd3dk93d3d0AAN0ASe4AT+4Anu4A7u5PAO5PT+5Pnu5P7u6eAO6eT+6enu6e7u7uAO7uT+7unu7u7u4AAP8AAP8AVf8Aqv8A//9VAP9VVf9Vqv9V//+qAP+qVf+qqv+q////AP//Vf//qv///ywAAAAAyAAyAAAI/wC7wcLXTWBBWAcTGlyIkGFBJQ4jNoS1TqLCiRczWtyIUeCuRiAbaWqkEWE4jiU1jurIMqXBcy1RCtzjzqA7hDe75dyJs2c3NDl1+uQp9CA5gTWHKi1KtOlSp0XXXLhQZGqSCyhIPu1m7KnXbn+KIsSJiClOHUnNFtUC9YFam2O7pXAZEyGaZHE7hmWYFi7dvzJj8qF6AQdhHFW1dFPDzCHCOu5eAZ6IRnLNohbzutSROWFOjJE/Y/bp9yaaboUK9tV8DbVBWKs9g54tu7bf27C1WJ1quPDUNd2sWG64DipuzGJbBh1m8/jN1hdrxu7W5PjomtQOTofl5rX2hZELdv9bpNMhUaQCe6CfuHp1uKCw+QrEYxi4kTWJqKKoyodZEox1tceXcqTB5hNOksXX0HcKytcQJxnBt4wxtUhTTC3FWGhMMcZcs0xjasX1WVpxrWeUed1A9sp2EdalkG5WAPcKHp5Ioltv3SSRYHkI2QKLKYEltBRDLYi34E61udigeQV2s4w042QojTFTSmNlMcJEaQwzGAHJooHrWbKQXyU62M0DIxqUC049pEWUEgZcoFgjWtgQWREoXNUNH5okhcZY7miBRiro/WkikgtVdptoYHoH33puRmddQ09mSKWUFlaZYS1ULjNmidzhJB6PB2GCVEckjpYQDJext1AvhOb/AepVOCjhhBLM5CTVBf/tAlFDftREnmNk2CYiQpIwdxM0jpIKoGfdINJSSwSBWhSVtYyT7aVVZsvpOJl6ClWq1irkmGqa8SSaaJ92Q9NCVxVBUhaSCdRIVRcY80oSdjboTnWPmnjuqa+Ru2A3wZLqXWmwVEJaHQIBw2BBzGw75aXTZFjMOMaAuynHXHZmInkjAgULBtJpVixmi1hjW5ILI4RCYavAksiKCHlSmBWe5JJEN7aQybBD5MSnqmrNOXZTv0km1YtBrFxnpEAQx8WMxhbWdIwxXF9zDYXFZJyxNJ6qmmZDNbm1IELkldgqo0gBd647DjPFYBGGNcbHqJ7g/0vSAqPlclF3a6s6rXfc2Y3gbQq12pl03RCalqUXS8YNtNhku6kxTI76LHsT5fJoR1MjLlZnDSlwAc97CpRzYUXs/StkQ8JyGpi04XQFi+50IeR3c+fluNCaNeTtOK258THXIT+57TjG+jXM2pc5Zy2YQaUs3rhwxYmDJ+7IrVMjq1+wt2IZuQoa49QVZOfQjY7uUNBNnme2dpbWckxBmlrJeTdX45g0akEwxzDnOD6xRcAY96xfLaQSGSmLQXBghQvgYU/uUAJCyGeYmzkwexYJz+FgoTaVTG0opLqJO24nl5j9zkQL0tw4dOGOq1lobNeYBQC9tTEQycdxAbOWNv8GlBK4jYgV1tqJVRphC8m0gHNSKYICGrGLvSGEJtMTmjtScx5RMaMxgCJTF1+IqvKwJUWxIVA3sGShXXgEG55iRtkKsQwBTgmMhkOXpMyyiaRUr36oOtiPlNWkq1ygEalCQW+YoQREuiGI2xsLeUBgEZLUKyJkxExrmiQiaMBmD9CCT1+6gSFtlSd9XBmgxl5zhXMBKFWgbEgJy5XE4mUSLvEaVnkGU5WfoYB3tJzaAlXBSZ2kpkmlO1BzwgiqNGqrY4AqUzeuUcqM/U9AQtGCqCTiR1EViHMsOh2QOteNqSgGFq/wBJ14Y4VG8OFmLcokuzoCPisMAkUNeVp4TAf/E+SkSmHBzEnHLFSeZXzNa7vQBZW4RTbTLex0LJxnEbuhgzbNhyhoO5aqDJMEJVQFX1I8ZN8S5EeH4OOMi3NTgTJBCDcqcyuTciXwHhUUrljKGMfAkpSkdDwqXQMhIELI+zRjJoC6yQ0TOUpoMOlCWlbQN4bBgSLP4AlmZAWgGhGTj073NIFQsiG7qMIVkvg4NdpMjw1S3xp2RE1tRSlT2OpY2DZ1Da1xKWUWPd2jaCe01xCqIdlpn/yAiLSO5CBe5bOCAhLRjVecAZG1DNEoT0cqI1TBjchRUm1q+gGK1vRZDIHITbBBOU4NMEputdQ1wGjQf5YoGT+EBURe0QlG/2iBEar4xZj6qj6BlOVAs6lJIxIREkJ4orGlEF9M2+WdstQki2NhRhW6oYq5mO4mj9ymkgoRm5qexx0SpJCWrmEhAS50gMyIZTq21JB3KTM2r2DEHXCrBjMw4iOMSAIjCki9hSARLJFsl/xeYwQtJMITa1qIBDULGwUaxFDdwEP1MAFGBapimdG6rouG5jBIxkWu0gDRMXSRDmFkamNIK0ZQ4abhbriivp5gBBKSgIQaa6ExnUhCyERJxIKYLJ7k7MZKQjS0phykIt7MCQcaC0BCEAIVsNjFgguL1s3WDpWQvFDG0sGciTBjgBn7KQCLERHCPsoTWUBCI2RcYxpnIf/GJPEEY0JbsB7Txr9pPJrRNhxZ6o2CDGS4QxUGgQjYViFkY+lOTdW0VJawkDSqMkZQNpatZawIPVx5qzRcugyavNS1BVFDFu7AjCy4OQt8UMUa0tyJPDBDDcPxcTfkRjrQbGIW1uoOb0fzSJTURMLXA49kqjCHTBiEEM4ta4ZjMs48M5CUHdOfQEjr0rZeSifMwOz6aOOORsBZxkn4iBn2gAjcagEJnnCDKvbrk9Ps4co8Ee2B+qJSBmnQRA4bYrrAo1SE1KsKhAhZN8zwW9U4MGZAJA1aQDMLbUyrLKpEXk06JR4eTqNsntKoRg3CZk+YQQ0CYUQmYKEKJGQhv2b/EAjIgwfkzxVkFAbhRDAZAnO4RMqbxzRI28TjiUEQQjtOFgg+xvKBUSAJtBgR000K/ql6j3kcGTsGQii0yWlG25SFANF0gpjmJFxBDUmA4JxhAW5GZMGNjCDJQig51Ojx9ZQG4hxCxlkgemt2n4Dk0i58PhFEpFzWo1yKg5FelJWwBIKwqZjG/rehbuwPFl/eGIUe3+KWvBkJ3cjCcd2RhYZ4OwuqaIQatFDuoSCCpi1B/EML10z/9jZpCFGChzEBeeoiGz2qGAT4YAGclyaEA/UGNUIk5t7R1JFKU0KI1zxDzfIWI+OXmez6TI35LOABIVl4NjKjZ5Nj1ps0kGtI/9ViKpq/Cs5fQimBTjJRBWMbxBNzuLBB0GKZ0o3oWX15D1pu8tdu/KomzpMhdQULxeBSOvEKNoR8xuBGdRBsGNV1r5AFYJR9GqU9A2NW3GdL3UAG2BNCyvE4knEHc5BFu3BhZkAIsMBFvgdCRZQdZYJ0pAV1HFIQq+UmpjA2O1V5GaEGNeYfupUjgxNZZxM9EgVCwsN6QzMLhKJFkIYQu3CCh/YaqkAIg4BoCoEJafRo50BZ3uQqfUFNmyINAiF3CnEIYKZakONdqKIFb7ZmxOQOe3Bc6PEKaLERLdc4IjM8bpMSReNPh8MMqoAIFwZpjSB/kEIGhoIqAAMeF5gqAv8lDRnDMbowTczkJFPiVpzSVElyCDR2B2smEKpwBw3BHPnFCCTFcpA0T9/HgfjUYggUT5CUWfLjTaeTYKoIe8UCKmB4Wq0hLg6BNR0jZg6IEcxgchKYfY2lBjQRX41gbI1Abp3gW8rkgQfBipgUfGSFeqhEfnTnULulgQVDeI6iXQXBDVDSMQsYGvWiINjQLdekR3rYDfzgW2m2BoywN+7gCfO1BnfQCSfnRs8YIRbhBVvIELBVTKkIC1FDVCwRfaTBKsRDWLiDKEm2TYy4FPgXXdS0JUSENrpgIa1xbxpIE9CwExFocrtwW+ATX5mQY2mmGGkHFx8QHlAxFqzAY7n/AxjCdDgyJUgwQ2Uad0KueCTTiDY7OSre8UWeAx6gQ1Gu0Q3eRmOqwINqcAdp1nVqVmrm0QWxmFFdBmRWxiAS9WxMCXdIQYazERdDxFwoVIecsI63BDN114H49zuiVX95UXJtmAlYSWMz9mpqtyQuEkROt3Ebpo0Ek1ZCQiKL2ITaEU1F0YcGUQmLwG3XkxTVUZRY9mlGom8YdhP+YWONwAR7cJVJUJpaISmAVBCelEcX+JXusIWzGE6dUxNRI1OvERZHghL91RGbBGruYCoPkhFIJAkfKCKXNkS24CVrswuliQTzRUX5pQp4pCDAtJitCHujAjeOiUlXRigAIyqi/2M91NhNLrFzWFV3kDKOlBUUbTMMb2ctzFCIavcaEtNoEwNJrZkTJTRYJVIkDvmYYakMcImbkIlU0XNlvWkWQZk9fEZlvEky3plHXCQQbhEkNsGB3TWYtiRNyJQHK7KWrpJCrRgw4bSauxUUiMcs6XJnM4dMhtldE1MQ0kKeuyYwGPmOY8I0MCoQumadpsOQr5FzLkROPVo8vwIhS4mjJFJS9TNkJ8qFAhqeM1pMOHo0Z+IuQekSW9ANlCQw96adTsojmZkqf3UUi1OkKJQZQZSZ0LIQiuFh3lGH7fZK2alGF7mhqKSYQ3k6/wUg2jA6emqUsJBsQlUT1uUTT+OiQ5dzhwNmIOjDbXCxBpGVQu/Voxd4EA4nkCTaHF0pTM3CqJD2UGVZiWIpMk3pQjh5KLBADzfRSvh3SUVBf92wqS/qqLYTE+ZBe6/RJi2gma8oIq9BDl6QjfiHZDC0PZmqqilRmZaqEYEnELBaJKfRORMxeOaiHNUhMH+QiwfxQV9hHgVagevzrA8FAiukpq9xGl8SlkHBQgEBADs=",
  "type": "image",
  "token": "aC_raGNycHQOSR7w0V7U0Ble-edJud_-AJofUvLFga8v59WsZVRI_RUBxC9Tk5eUoBNrdPhqA0M_ZkT0V0le909Z7YmWHVT4Yead026_",
  "expires_in": 300
}

字段说明​

响应参数​

字段名类型必填说明
datastring是图片数据，RFC 2397标准的内联图片数据URI，包含协议头(data:)、MIME类型(image/gif)、编码方式(base64)和实际数据
typestring是资源类型，固定值为"image"
tokenstring是验证码token，用于后续验证接口
expires_ininteger是过期时间，单位为秒，默认300秒

使用流程​

1. 获取验证码图片​

  • 前端调用该接口获取验证码数据
  • 将返回的data字段直接作为<img src>的值渲染
  • 在本地存储中保存返回的token（建议使用localStorage）

2. 用户输入验证码​

  • 用户识别图片中的验证码内容
  • 在输入框中输入识别的验证码

3. 提交验证码验证​

4. 业务接口鉴权​

  • 在需要验证码保护的业务请求中附加请求头
  • 请求头格式：x-captcha-token: xxx

关键特性​

图片格式​

  • 符合RFC 2397标准的Data URI
  • 使用GIF格式
  • Base64编码
  • 可直接在HTML中使用

安全性​

  • 验证码token有效期为300秒
  • 每次获取生成新的验证码
  • 验证码使用后立即失效
  • 支持防暴力破解机制

使用场景​

登录保护​

  • 用户登录失败次数过多时要求验证码
  • 防止暴力破解密码
  • 保护账号安全

注册保护​

  • 防止批量注册
  • 防止恶意注册
  • 保护系统资源

敏感操作保护​

  • 找回密码
  • 修改密码
  • 修改绑定信息
  • 删除账号

注意事项​

前端实现​

  • 将data字段直接赋值给img标签的src属性
  • 妥善保存token用于后续验证
  • 实现刷新验证码功能
  • 验证码过期后需重新获取

安全建议​

  • 验证码应在服务端生成
  • 验证码内容应随机且不可预测
  • 限制同一IP的获取频率
  • 记录验证码获取日志

常见错误​

  • 服务器错误：重试获取
  • 网络超时：检查网络连接
  • 频率限制：等待后重试

错误响应示例​

{
  "error": "rate_limit_exceeded",
  "error_code": 4029,
  "error_description": "获取验证码频率过高，请稍后重试"
}

相关接口​

Request​

Responses​

Response Headers
    Schema
      data 图片数据 (string)required

      RFC 2397标准的内联图片数据URI，包含以下部分：协议头：data: MIME类型：image/gif 编码方式：base64 实际数据：符合RFC 4648的Base64编码二进制数据

      type 类型 (string)required

      资源类型枚举值: "image" 图片类资源。其他值保留未来扩展

      token token (string)required

      验证码验证接口需要传入的token

      expires_in 过期时间 (integer)required

      令牌过期时间，默认300秒

    Loading...