API 开发文档

完整的API接口说明，帮助您快速集成海报生成功能

快速开始

海宝海报API提供RESTful接口，支持JSON格式的数据交换。所有API请求都需要通过HTTPS发送到我们的服务器。

基础URL

https://api.haibao.com/v1

请求格式

所有请求都使用JSON格式，Content-Type设置为application/json。

响应格式

所有响应都使用JSON格式，包含以下字段：

{
  "code": 0,           // 状态码，0表示成功
  "message": "success", // 响应消息
  "data": {},          // 响应数据
  "timestamp": 1640995200 // 时间戳
}

身份验证

所有API请求都需要在请求头中包含API密钥进行身份验证。

获取API密钥

登录您的账户，在API设置页面生成API密钥。

使用API密钥

在请求头中添加Authorization字段：

Authorization: Bearer YOUR_API_KEY
注意：请妥善保管您的API密钥，不要在客户端代码中暴露。

模板管理

获取模板列表

GET/templates

请求参数

参数 类型 必填 说明
category_id integer 否 分类ID，用于筛选特定分类的模板
page integer 否 页码，默认为1
limit integer 否 每页数量，默认为20，最大100

响应示例

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "templates": [
      {
        "id": "template_001",
        "name": "促销海报模板",
        "category": "电商",
        "width": 1080,
        "height": 1920,
        "thumbnail": "https://cdn.haibao.com/templates/001_thumb.jpg",
        "preview": "https://cdn.haibao.com/templates/001_preview.jpg"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

获取模板详情

GET/templates/{template_id}

路径参数

参数 类型 必填 说明
template_id string 是 模板ID

海报生成

生成海报

POST/posters/generate

请求参数

参数 类型 必填 说明
template_id string 是 模板ID
elements array 是 元素配置数组
format string 否 输出格式，支持jpg、png，默认为jpg
quality integer 否 图片质量，1-100，默认为90

请求示例

{
  "template_id": "template_001",
  "elements": [
    {
      "type": "text",
      "key": "title",
      "content": "限时特惠",
      "style": {
        "fontSize": 48,
        "color": "#ff0000",
        "fontWeight": "bold"
      }
    },
    {
      "type": "image",
      "key": "product_image",
      "url": "https://example.com/product.jpg",
      "style": {
        "fit": "cover",
        "borderRadius": 8
      }
    }
  ],
  "format": "jpg",
  "quality": 90
}

响应示例

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "poster_id": "poster_123456",
    "poster_url": "https://cdn.haibao.com/posters/poster_123456.jpg",
    "width": 1080,
    "height": 1920,
    "size": 245760,
    "created_at": "2024-01-01T12:00:00Z"
  }
}

元素类型

文本元素

用于添加文本内容到海报中。

{
  "type": "text",
  "key": "title",
  "content": "文本内容",
  "style": {
    "fontSize": 24,
    "color": "#000000",
    "fontWeight": "normal",
    "textAlign": "left",
    "lineHeight": 1.5
  }
}

图片元素

用于添加图片到海报中。

{
  "type": "image",
  "key": "product_image",
  "url": "https://example.com/image.jpg",
  "style": {
    "fit": "cover",
    "borderRadius": 8,
    "opacity": 1.0
  }
}

二维码元素

用于生成二维码。

{
  "type": "qrcode",
  "key": "qr_code",
  "content": "https://example.com",
  "style": {
    "size": 200,
    "fgColor": "#000000",
    "bgColor": "#ffffff",
    "ecc": "M"
  }
}

条形码元素

用于生成条形码。

{
  "type": "barcode",
  "key": "barcode",
  "content": "123456789012",
  "style": {
    "format": "CODE128",
    "height": 100,
    "lineWidth": 2
  }
}

批量生成

批量生成海报

POST/posters/batch

批量生成功能允许您一次生成多张海报，提高效率。

请求参数

参数 类型 必填 说明
template_id string 是 模板ID
batch_data array 是 批量数据数组，每个元素包含elements配置

请求示例

{
  "template_id": "template_001",
  "batch_data": [
    {
      "elements": [
        {
          "type": "text",
          "key": "title",
          "content": "商品A"
        }
      ]
    },
    {
      "elements": [
        {
          "type": "text",
          "key": "title",
          "content": "商品B"
        }
      ]
    }
  ]
}

错误处理

错误响应格式

错误响应

{
  "code": 400,
  "message": "参数错误",
  "error": {
    "type": "validation_error",
    "details": "template_id 参数不能为空"
  },
  "timestamp": 1640995200
}

常见错误码

错误码 说明 解决方案
400 请求参数错误 检查请求参数格式和必填字段
401 身份验证失败 检查API密钥是否正确
403 权限不足 检查API密钥权限
404 资源不存在 检查模板ID或资源路径
429 请求频率超限 降低请求频率
500 服务器内部错误 联系技术支持

频率限制

为了保护服务稳定性，我们对API请求频率进行了限制：

  • 基础版：每分钟100次请求
  • 专业版：每分钟1000次请求
  • 企业版：每分钟5000次请求
提示：超出频率限制时，API会返回429错误码。建议在客户端实现请求重试机制。

频率限制响应头

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995260