公共样式API接口文档

本文介绍如何调用草料「公共样式 API」——也就是草料标签样式库里的公共样式——在自有系统或网页里批量生成不同内容的二维码标签。适合想直接用草料提供的通用样式、不需要额外在后台设置的场景。

与私有样式相比，公共样式 API 无需登录账号、无需生成签名，只要拿到样式编号就能调。

二维码标签生成示例

不清楚私有样式和公共样式的差别？先看一物一码标签制作API，里面有两种方式的对比。

前置条件

开始前请确认：

已在草料标签样式库中选好要用的公共样式，记下它的样式编号（例如 B572）。
了解该样式有几个字段、字段顺序以及类型（文本 / 图片），决定需要传哪些动态字段。
自有系统具备发起 HTTP GET 请求的能力。

一、找到公共样式编号

打开草料标签样式库。
选择一个标签样式，在列表页可直接看到样式编号，也可以进入详情页点击「调用 API 制作」查看。
记下样式编号（下文以 B572 为例），并留意该样式字段的顺序和类型。

二、接口说明

请求地址与方式

URL：https://open-api.cli.im/cli-open-platform-service/v1/labelStyle/create
方式：GET

请求参数

参数名称	是否必填	类型	说明
`cliT`	是	string	公共样式编号，例如 `B572`
`cliD`	是	string	二维码中承载的内容。字节越多，二维码图案越密，建议控制在 1500 字节以内
`return_file`	是	string	返回类型。不传值时返回二进制图片流；传 `base64` 时返回 base64 编码
`theme_color`	是	string	主题颜色，十六进制色值，例如 `#166BC7`；不需要自定义时可传空
`cliF`	否	string	动态文本字段，按字段顺序传入。如样式有 3 个文本字段，传 `cliF1=xx&cliF2=xx&cliF3=xx`
`cliP`	否	string	动态图片字段，按字段顺序传入，需传公网可访问的静态图片地址。如样式第 2 个字段是图片、其余是文本，传 `cliF1=xx&cliP2=xx&cliF3=xx&cliF4=xx`

注：cliF 和 cliP 是一组按位置区分类型的动态字段。数字下标对应样式中第几个字段，字母区分类型（F = 文本，P = 图片）。你只需要按样式里字段的实际顺序传即可。

三、发送请求

把参数按样式要求拼到 URL 上，发 GET 请求即可。

请求示例（以 B572 样式为例，最多 7 个字段，第 3 个是图片、其余是文本，所以动态字段是 cliF1、cliF2、cliP3、cliF4…cliF7）：

https://open-api.cli.im/cli-open-platform-service/v1/labelStyle/create?cliT=B572&cliD=图片样式二维码&cliF1=人员实名信息卡&cliF2=安全生产，人人有责&cliP3=https://ncstatic.clewm.net/rsrc/2023/0612/13/952a04c092275a684025ef0d2ed6bcce.png&cliF4=张栋旭&cliF5=设备操作员&cliF6=工号：MH-0403&cliF7=部门：现场项目部&return_file=

返回结果

return_file 未传 → 返回二进制图片流
return_file=base64 → 返回图片的 base64 编码，可直接嵌入网页或传给其他系统

返回示例：

文件图片

如何确认调用成功

响应状态码为 200，且返回体是图片流（或 base64 字符串）
保存为 .png 文件后能正常打开，标签内容符合预期

如果返回体是 JSON，多半是报错了，参考下面的错误码排查。

错误码

错误码	含义	解决方案
200	成功	正常返回图片
400	请求的数据格式不符	检查参数是否完整、格式是否正确
40000	系统繁忙	系统可能在维护升级，稍后重试
40001	参数错误	对照文档检查参数名和值是否正确

四、完整代码示例

以 B572 样式为例，最多 7 个字段，第 3 个是图片、其余是文本：

package org.cli.platform.service.util;

import org.apache.commons.io.IOUtils;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import org.springframework.web.util.UriUtils;


public class CliApiV1Demo {
    public static void main(String[] args) throws IOException {
        String cliD = UriUtils.encode("图片样式二维码", StandardCharsets.UTF_8.name());
        String cliF1 = UriUtils.encode("人员实名信息卡", StandardCharsets.UTF_8.name());
        String cliF2 = UriUtils.encode("安全生产，人人有责", StandardCharsets.UTF_8.name());
        String cliP3 = UriUtils.encode("https://ncstatic.clewm.net/rsrc/2023/0612/13/952a04c092275a684025ef0d2ed6bcce.png", StandardCharsets.UTF_8.name());
        String cliF4 = UriUtils.encode("张栋旭", StandardCharsets.UTF_8.name());
        String cliF5 = UriUtils.encode("设备操作员", StandardCharsets.UTF_8.name());
        String cliF6 = UriUtils.encode("工号：MH-0403", StandardCharsets.UTF_8.name());
        String cliF7 = UriUtils.encode("部门：现场项目部", StandardCharsets.UTF_8.name());
        URL url = new URL("http://open-api.cli.im/cli-open-platform-service/v1/labelStyle/create?cliT=B572&cliD=" + cliD + "&return_file=&theme_color=&cliF1=" + cliF1 + "&cliF2=" + cliF2 + "&cliP3=" + cliP3 + "&cliF4=" + cliF4 + "&cliF5=" + cliF5 + "&cliF6=" + cliF6 + "&cliF7=" + cliF7);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setDoOutput(true);
        connection.setRequestMethod("GET");
        connection.connect();

        InputStream stream = connection.getInputStream();
        FileOutputStream out = new FileOutputStream(new File("test.png"));
        IOUtils.copy(stream, out);
    }
}

提示：含中文或特殊字符的参数值必须做 URL 编码，代码里用 UriUtils.encode 处理，其他语言里用各自标准库的 URL 编码方法即可。

调用限制

Beta 期间：已开通 API 的用户可长期免费调用
并发限制：单 IP 秒级并发 30 次，需要更高并发请前往社区反馈
调用问题：遇到流程、速度等问题也可在社区反馈，官方顾问和技术会定期查看回复

前置条件​

一、找到公共样式编号​

二、接口说明​

请求地址与方式​

请求参数​

三、发送请求​

返回结果​

如何确认调用成功​

错误码​

四、完整代码示例​

调用限制​

相关参考​