API文档 图库 视频 音频 字体

对接指南

1、咨询客户经理。
  • 客户经理邮箱:xingyu@zcool.com.cn
2、浏览API文档,根据实际需求选择合适的API。以下是通用接入案例参考:
  • 2.1 搜索API、分类搜索API、专题搜索API、相似搜索API
  • 2.2 详情API
  • 2.3 购买API、我的购买记录API、历史购买再下载API、购买记录详情API
  • 2.4 授权书下载API
3、获取代表您身份的应用ID和应用密钥 client_idclient_secret (正式环境、测试环境各一份)
4、开发调试。
5、测试完成后部署上线。
  • 请使用测试应用的 client_id 进行测试,在测试过程中购买的动作不会真实提交,无需支付。请放心地使用我们的API进行测试。

技术必看

1、API请求说明
  • 基础地址:https://api.hellorf.com/plus/{endpoint}

  • 基础参数

    参数 必选 类型 名称 说明
    client_id string 客户应用id 从上一步对接指南获取
    nonce_str string 安全随机字符串 当前时间戳(秒),10分钟内有效期
    sign string 安全签名 见下一节
  • 安全签名规则:

    • (1) 将所有请求参数,按参数名key,ASCII码正序,不包括 sign 和 client_secret,形如:

          [
              "client_id":"4fiodcz8xjl6p8nbzfex2",
              "keyword":"云南",
              "nonce_str":"1473820208"
          ]
    • (2) 进行 URL 编码,生成字符串,形如:

      client_id=4fiodcz8xjl6p8nbzfex2&keyword=云南&nonce_str=1473820208

    • (3) 在末尾拼接上应用密钥(即client_secret),形如:

      client_id=4fiodcz8xjl6p8nbzfex2&keyword=云南&nonce_str=1473820208&client_secret=9b530aa85723c06a90879bee8f5096d7

    • (4) 最后计算字符串的 MD5 哈希值,得到 32 位小写的安全签名,形如:

      00ba2da066957662f43b668cf208e827

2、API响应说明
  • 响应数据,基本以 JSON 格式返回,文件会以 FILE 格式返回。

  • 请求失败的响应范例:

    {
        "result": false,
        "message": '失败原因',
        "code": 1001
    }
  • 请求成功的响应范例

    {
        "result": true,
        "data": {}
    }

开发SDKs

为了更高效地对接,我们提供了 Java、Go 和 PHP 三种语言的 SDK 示例(软件开发工具包),建议您参考使用。

点我前往

同时,我们也会准备相应的 Postman 调试配置,配合 nonce_str、sign 的10分钟有效期,方便您快速调试。

敬请期待

问 & 答

1. 购买获取的图片有尺寸限制吗,可以获得更大的尺寸吗?

购买图片API返回的尺寸是由商务谈定的,如需调整需要与商务联系协商。

2. 购买使用的 permission_id 如何获取?

您可以通过调用图片详情API来查询对应图片的 permission_id。

3. 为什么有时候通过图片名称搜索不出匹配名称的图片,怎样进行搜索?

1、图片搜索与文章咨询不同,它基于图片转文字算法生成n多个匹配标签,并不是以图片标题为唯一的检索依据。因此,当您尝试使用部门名称等文字内容无法检索到图片时,建议尝试使用图片元素作为关键字,例如颜色、形状和环境中的物品等,并在搜索框中输入这些关键词。请注意,搜索关键字应拆分成多个单独的单词,不支持短语搜索。
2、要进行高级的条件搜索,可以使用 and、or、not 和() 组合连接多个关键字,达到使用逻辑语句查询的高级功能。

4.热门排序是否基于全部图片进行排序?

不是。热门排序仅展示具有热度值的图片,而并非所有图片都有热度值。

5. preview_url 和 preview260_url 有什么区别?

preview_url 有水印,最大宽为450像素的缩略图,通常用作瀑布流展示。
preview260_url 无水印,最大高为260像素的缩略图,通常用作列表展示。

6. 搜索图片返回的链接过期时间是多久?

10分钟。

音乐分类API

  • 接口地址 audio/categories

  • 请求方法 GET

  • 参数列表

  • 返回结果

{
  "result": true,
  "data": [
    "genres": [   //音乐风格
            {
                "id": 1354,
                "name": "现代交响"
            },
            {
                "id": 1356,
                "name": "中国民族"
            },
        ],
        "moods": [  //音乐情感
            {
                "id": 1350,
                "name": "宽广/磅礴"
            },
            {
                "id": 1351,
                "name": "戏剧的"
            },
        ],
        "instruments": [  //音乐乐器
            {
                "id": 1353,
                "name": "弦乐组"
            },
            {
                "id": 1391,
                "name": "中国民族乐器"
            },
        ],
        "bpms": [   //音乐节奏
            {
                "id": 1,
                "name": "非常慢(0-60 bpm)"
            },
            {
                "id": 2,
                "name": "缓慢(60-100 bpm)"
            },
            {
                "id": 3,
                "name": "适中(100-120 bpm)"
            },
            {
                "id": 4,
                "name": "充满活力(120-140 bpm)"
            },
            {
                "id": 5,
                "name": "快速(140-160 bpm)"
            },
            {
                "id": 6,
                "name": "非常快(160-400 bpm)"
            }
        ]
  ]
}
  • 接口地址 audio/search

  • 请求方法 GET

  • 参数列表

    参数名 必填 类型 说明
    keyword string 查询的关键字
    mood_id int 心情 id
    genre_id int 风格 id
    bpm_id int 节奏 id
    duration_from int 开始时长
    duration_to int 结束时长
    instrument_id int 乐器 id
    level_type int 等级 1:Absolute 2:Boost 3:Chic 99:Shutterstock 100:Shutterstock 优选
    is_vhifun int 是否是vhifun 传值1
    can_purchase int 筛选可购买 传值 1
    page int 哪一页 默认第一页
    per_page int 每页数量 默认 30
  • 返回结果

{
  "result": true,
  "data": {
    "current_page": 1, //当前页
    "per_page": 100, //每页数量
    "total": 10763, //总数量
    "list": [
      {
        "id": 505947,
        "title": "Beginner's Luck",
        "bpm": 95,
        "preview_mp3_url": "https://hellorfaudio.zcool.cn/audio/local/preivew/5b90e01b9eef7717505947.mp3",
        "waveform_url": "https://hellorfaudio.zcool.cn/audio/local/wave/5b90e01b9eef7717505947.png",
        "origin_waveform_url": "https://hellorfaudio.zcool.cn/audio/local/wave/5b90e01b9eef7717505947.json",
        "artist": "Z01803360",    //作者/艺术家
        "duration": 28,
        "description": "",
        "genres": [],
        "moods": [],
        "instruments": [
          {
              "id": 80,
              "name": "小提琴"
          },
          {
              "id": 81,
              "name": "大提琴"
          }
        ]
      },
      ]
  }
}

音乐详情API

  • 接口地址 audio/detail

  • 请求方法 GET

  • 参数列表

    参数名 必填 类型 说明
    audio_id true int 音乐 ID
  • 返回结果

{
  "result": true,
  "data": {
    "audio": {
        "type": "签约供应商",
        "id": 505947,
        "title": "Beginner's Luck",
        "bpm": 95,
        "preview_mp3_url": "https://hellorfaudio.zcool.cn/audio/local/preivew/5b90e01b9eef7717505947.mp3",
        "waveform_url": "https://hellorfaudio.zcool.cn/audio/local/wave/5b90e01b9eef7717505947.png",
        "origin_waveform_url": "https://hellorfaudio.zcool.cn/audio/local/wave/5b90e01b9eef7717505947.json",
        "artist": "Z01803360",
        "duration": 28,
        "description": "",
        "genres": [],
        "moods": [],
        "instruments": [
            {
                "id": 80,
                "name": "小提琴"
            },
            {
                "id": 81,
                "name": "大提琴"
            },
            {
                "id": 612,
                "name": "巴松管"
            },
        ]
    },
    "permissions": [
        {
            "id": 35,
            "name": "SSTK音乐-全媒体",
            "price": "21.00",
            "type": "all",
            "duration": "00:02:00",   //时长
            "bpm": 120                //每一分钟的节拍数量
        },
    ]
}

购买音乐API

  • 接口地址 audio/purchase

  • 请求方法 POST

  • 参数列表

    参数名 必填 类型 说明
    audio_id int 音乐 ID
    permission_id int 权限 ID
    warrant_name string 授权用户名称
    third_user_id string 第三方用户 ID
  • 返回结果

{
  "result": true,
  "data": {
    "id": 442,    //购买ID
        "url": "https://preview-audio.oss-cn-beijing.aliyuncs.com/audios/hifive-listen/512797.mp3?response-content-disposition=attachment%3Bfilename%3D512797.mp3&OSSAccessKeyId=LTAI4FvyBjoFRCwBPtqSe4Mc&Expires=1649324720&Signature=9opVTvdYMY7%2BkyqA74Q%2Fyu3Sr5w%3D"    //下载地址
  }
}

我的购买记录API

  • 接口地址 audio/my-purchases

  • 请求方法 GET

  • 参数列表

    参数名 必填 类型 说明
    begin_at TIMESTAMP 开始时间 例如:2017-01-01 23:23:23
    end_at TIMESTAMP 结束时间 例如:2017-01-01 23:23:23
    is_download int 是否下载 默认值全部 1 是 2 否
    audio_id int 音乐 ID
    per_page int 每页数量 默认值 10
    page int 哪一页 默认值第一页
  • 返回结果

{
    "result": true,
    "data": {
        "current_page": 1, //当前页
        "per_page": "10",
        "total": 1,
        "list": [
            {
                "id": 178,
                "plus_user": {
                    "id": 14949528,
                    "name": "didi"
                },
                "real_plus_user": {
                    "id": 14949528,
                    "name": "didi"
                },
                "third_user_id": "",
                "plus_permission": {
                    "id": 33,
                    "name": "HD"
                },
                "able_id": 8126014,
                "able_type": "audio",
                "asset_type": "hd",
                "warrant_name": "广州汽车集团股份有限公司",
                "download_at": "2016-08-29 17:09:02",
                "created_at": "2016-08-29 16:41:47"
            }
        ]
    }
}

购买记录详情API

  • 接口地址 audio/purchase-detail

  • 请求方法 GET

  • 参数列表

    参数名 必填 类型 说明
    purchase_id int 购买 ID
  • 返回结果

{
  "result" : true,
  "data" : {
    "audio" : {
        "type": "签约供应商",
        "id": 505947,
        "title": "Beginner's Luck",
        "bpm": 95,
        "preview_mp3_url": "https://hellorfaudio.zcool.cn/audio/local/preivew/5b90e01b9eef7717505947.mp3",
        "waveform_url": "https://hellorfaudio.zcool.cn/audio/local/wave/5b90e01b9eef7717505947.png",
        "origin_waveform_url": "https://hellorfaudio.zcool.cn/audio/local/wave/5b90e01b9eef7717505947.json",
        "artist": "Z01803360",
        "duration": 28,
        "description": "",
        "genres": [],
        "moods": [],
        "instruments": [
            {
                "id": 80,
                "name": "小提琴"
            },
            {
                "id": 81,
                "name": "大提琴"
            },
            {
                "id": 612,
                "name": "巴松管"
            },
        ]
    },
    "purchase" : {
      "id" : 1, // 购买记录ID
      "permission_id" : 27, // 权限ID
      "permission_name" : "xxxxx", // 权限名称
      "plus_user_id" : 14627888, // 主账号ID
      "real_plus_user_id" : 14627888, // 实际购买账号ID
      "price" : "812.50", // 价格
      "asset_type" : "huge_jpg", // 购买尺寸
      "warrant_name" : "测试", // 授权主体名称
      "fileSize" : "11.5MB", // 所够买尺寸对应文件大小
      "created_at" : "2016-06-24 09:24:33" // 购买时间
    }
  }
}

授权书下载API

  • 接口地址 audio/download-warrant

  • 请求方法 GET

  • 参数列表

    参数名 必填 类型 说明
    purchase_id int 购买 ID
  • 返回结果

FILE

历史购买再下载API

  • 接口地址 audio/purchase-download

  • 请求方法 GET

  • 参数列表

    参数名 必填 类型 说明
    purchase_id int 购买 ID
  • 返回结果

{
    "result": true,
    "data": {
        "url": "https://preview-audio.oss-cn-beijing.aliyuncs.com/audios/hifive-listen/512797.mp3?response-content-disposition=attachment%3Bfilename%3D512797.mp3&OSSAccessKeyId=LTAI4FvyBjoFRCwBPtqSe4Mc&Expires=1649328386&Signature=SRZ7oFMcH4u%2FMcR9eEct8FCSNM8%3D"   //下载地址
    }
}