API文档
API文档

图库接口文档说明

接口规范

联系方式：huxiongfei@zcool.com.cn

  • 请求方式：HTTP
  • 请求地址：https://api.hellorf.com/plus/

  • 公共参数

    参数 必选 类型及范围 说明
    client_id true string client_id
    nonce_str true string 时间戳
    sign true string 签名

    • 随机字符串参数：

      请求的接口中必须包含字段nonce_str，该字段以当前时间戳（秒）对应的字符串作为参数值

    • 参数签名：

      将所有接收到非空参数（包含随机数参数，不包含签名及密钥参数），按照参数名ASCII码从小到大排序，将参数对应的url编码作为字符串，形如

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

      将得到的字符串拼接上密钥，形如

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

      将得到的字符串用md5加密，得到32位小写加密串 sign=00ba2da066957662f43b668cf208e827

      {
    "client_id": "4fiodcz8xjl6p8nbzfex2",
    "keyword": "云南",
    "nonce_str": 1473820208,
    "sign": "00ba2da066957662f43b668cf208e827"
}

  • 返回说明

    • 所有的返回数据以JSON格式提供
  • 请求失败范例
{
  "result": false,
  "message": '',
  "code": 1001
}
  • 请求成功范例
{
  "result": true,
  "data": {}
}

图片分类

  • 接口地址 image/categories

  • 请求方式 GET

  • 请求参数

  • 返回结果
{
  "result": true,
  "data": [
    {
      "id": 0,
      "name": "交通运输"
    },
    {
      "id": 16,
      "name": "科技"
    }
  ]
}

  • 接口地址 image/search

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
    keyword true string 查询的关键字
    page true int 哪一页
    per_page false int 每页数量 最大值100
    category false string 分类ID
    image_type false string 图片类型：全部为空，照片 photo, 插画 illustration, 尺量图 vector
    color false string 颜色:#0ecb9b,#0bbbf5,#1f55f8,#0000ff,#7f00ff,#bf00ff,#ea06b1,#e72525,#f48700,#eca71d,#f1f129,#a9e418,#06d506,#000000
    height false int 高
    width false int 宽
    orientation false string 图片方向: horizontal, vertical
    people_age false string 图片人物年龄段 infants, children, teenagers, 20s, 30s, 40s, 50s, 60s, older
    people_gender false string 性别 male, female, both
    people_number false string 人数
    people_model_released false boolean 是否含有肖像权
    origin false boolean 是否只看国内
    people_ethnicity false string 种族：黑人black,白人caucasian,拉美西班牙裔hispanic，中东人middle_eastern，东南亚人southeast_asian，中国人chinese
    contributor false string 作者名称
    width_from false int 起始宽
    width_to false int 终止宽
    height_from false int 起始高
    height_to false int 终止高
    sort false string 排序，最新：newest，热门：popular（默认）
  • 返回结果
{
  "result": true,
  "data": {
    "per_page": 100, //每页数量
    "total": 10763, //总数量
    "list": [
      {
        "id": "363488282",
        "aspect": 1.4984, //宽高比
        "title": "云南洱海",
        "large_thumb_url": "https://thumb9.shutterstock.com/thumb_large/131785/363488282/stock-photo-amazing-view-of-the-jade-dragon-snow-mountain-and-the-black-dragon-pool-lijiang-yunnan-province-363488282.jpg",
        "preview_url": "https://image.shutterstock.com/display_pic_with_logo/131785/363488282/stock-photo-amazing-view-of-the-jade-dragon-snow-mountain-and-the-black-dragon-pool-lijiang-yunnan-province-363488282.jpg",
        "preview_large_url": "https://image.shutterstock.com/z/stock-photo-363488282.jpg",
        "preview260_url": "https://image.shutterstock.com/z/stock-photo-363488282.jpg"
      },
      {
        "id": 2234602517,
        "aspect": "1.50",
        "title": "云南洱海",
        "large_thumb_url": "http://ali.image.hellorf.com/hellorf/fd/7d/ae6ed152b5c0785e037fed7d7328/thumb_s_2234602517.jpg",
        "preview_url": "http://ali.image.hellorf.com/hellorf/fd/7d/ae6ed152b5c0785e037fed7d7328/thumb_b_2234602517.jpg",
        "preview_large_url": "http://hellorfimg.zcool.cn/provider_image/large/2234602517.jpg",
        "preview260_url": "https://image.shutterstock.com/z/stock-photo-363488282.jpg"
      }
    ]
  }

  • 接口地址 image/v2/search

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
    keyword true string 查询的关键字
    page true int 哪一页
    per_page false int 每页数量 最大值100
    category false string 分类ID
    image_type false string 图片类型：全部为空，照片 photo, 插画 illustration, 尺量图 vector
    width_from false int 起始宽
    width_to false int 结束宽
    height_from false int 起始高
    height_to false int 结束高
    orientation false string 图片方向: horizontal, vertical
    origin false boolean 是否只看国内
  • 返回结果
{
    "result": true,
    "data": {
        "per_page": 100,
        "total": 2,
        "list": [
            {
                "id": "1111435439",
                "aspect": 1.498,
                "title": "close up of cosmos flowers in the garden",
                "large_thumb_url": "https://thumb1.shutterstock.com/thumb_large/4244749/1111435439/stock-photo-close-up-of-cosmos-flowers-in-the-garden-1111435439.jpg",
                "preview_url": "https://image.shutterstock.com/display_pic_with_logo/4244749/1111435439/stock-photo-close-up-of-cosmos-flowers-in-the-garden-1111435439.jpg",
                "preview_large_url": "https://image.shutterstock.com/z/stock-photo-1111435439.jpg",
                "preview260_url": "https://image.shutterstock.com/image-photo/-260nw-1111435439.jpg",
                "image_type": "photo",
                "categories": [
                    "12"
                ],
                "preview_width": 450,
                "preview_height": 300
            },
            {
                "id": "1111436675",
                "aspect": 1.3333,
                "title": "lungwort, pulmonaria, small blue, purple and pink flowers",
                "large_thumb_url": "https://thumb9.shutterstock.com/thumb_large/194017232/1111436675/stock-photo-lungwort-pulmonaria-small-blue-purple-and-pink-flowers-1111436675.jpg",
                "preview_url": "https://image.shutterstock.com/display_pic_with_logo/194017232/1111436675/stock-photo-lungwort-pulmonaria-small-blue-purple-and-pink-flowers-1111436675.jpg",
                "preview_large_url": "https://image.shutterstock.com/z/stock-photo-1111436675.jpg",
                "preview260_url": "https://image.shutterstock.com/image-photo/-260nw-1111436675.jpg",
                "image_type": "photo",
                "categories": [
                    "12"
                ],
                "preview_width": 450,
                "preview_height": 337
            }
        ]
    }
}

图片详情

  • 接口地址 image/detail

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
    image_id true string 图片ID
  • 返回结果
{
    "result": true,
    "data": {
        "image": {
            "_id": "1111435439",
            "aspect": 1.498,
            "image_type": "photo",
            "large_thumb_url": "https://thumb1.shutterstock.com/thumb_large/4244749/1111435439/stock-photo-close-up-of-cosmos-flowers-in-the-garden-1111435439.jpg",
            "category_ids": [
                "12"
            ],
            "title": "close up of cosmos flowers in the garden",
            "id": "1111435439",
            "keywords": [],
            "extension": "jpg",
            "origin_thumb_url": "https://image.shutterstock.com/z/stock-photo-1111435439.jpg",
            "preview_url": "https://image.shutterstock.com/display_pic_with_logo/4244749/1111435439/stock-photo-close-up-of-cosmos-flowers-in-the-garden-1111435439.jpg"
        },
        "author": "Jantana Phattha",
        "permissions": [
            {
                "id": 13470,
                "name": "图片样片",
                "price": "0.00",
                "text": "1000 x 668 px (72dpi)",
                "size": "556.7KB",
                "size_level": 4,
                "width": 1000,
                "height": 668,
                "dpi": 72
            },
            {
                "id": 13493,
                "name": "图片样片",
                "price": "0.00",
                "text": "1000 x 668 px (72dpi)",
                "size": "556.7KB",
                "size_level": 4,
                "width": 1000,
                "height": 668,
                "dpi": 72
            }
        ]
    }
}

购买图片

  • 接口地址 image/purchase

  • 请求方式 POST

  • 请求参数

    参数名 必选 类型 说明
    image_id true int 图片ID
    permission_id true int 权限ID
    warrant_name true string 授权用户名称
    third_user_id false string 第三方用户ID 平台方必传
  • 返回结果
{
  "result": true,
  "data": {
    "id": 52,
    "url": "http://download.hellorf.com/hellorf/6b/0f/be36d08b8498c9a619608c089115/hellorf_2234567973.jpg"  //下载地址
  }
}

热门专题列表

  • 接口地址 image/topic/hots

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
  • 返回结果
{
  "result": true,
  "data": [
    {
      "id": 1,
      "title": "Night office",
      "cover_image":""
    },
    {
      "id": 2,
      "title": "双重曝光",
      "cover_image":""
    },
    {
      "id": 3,
      "title": "首页大图",
      "cover_image":""
    }
  ]
}

专题详情

  • 接口地址 image/topic/{$id}

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
  • 返回结果
{
  "result": true,
  "data": {
    "id": 1,
    "title": "Night office",
    "list": [
      {
        "id": 131096951,
        "aspect": "1.5026",
        "description": "LONDON - JAN 31: people work in an office building in London on January 31, 2013. Full-time employees in the UK work longer hours than the EU average, according to the Office for National Statistics.",
        "large_thumb_url": "http://thumb109.test-ss.cn/thumb_large/595720/131096951/stock-photo-london-jan-people-work-in-an-office-building-in-london-on-january-full-time-131096951.jpg",
        "preview_url": "http://thumb109.test-ss.cn/display_pic_with_logo/595720/131096951/stock-photo-london-jan-people-work-in-an-office-building-in-london-on-january-full-time-131096951.jpg"
      },
      {
        "id": 110352362,
        "aspect": "1.5",
        "description": "office buildings",
        "large_thumb_url": "http://thumb106.test-ss.cn/thumb_large/496018/110352362/stock-photo-office-buildings-110352362.jpg",
        "preview_url": "http://thumb106.test-ss.cn/display_pic_with_logo/496018/110352362/stock-photo-office-buildings-110352362.jpg"
      }
    ]
  }
}

相似图片

  • 接口地址 image/{$id}/similar

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
  • 返回结果
{
  "result": true,
  "data": [
    {
      "id": "314834948",
      "aspect": 1.5,
      "description": "Head and shoulders portrait of a young businesswoman smiling",
      "large_thumb_url": "http://thumb109.test-ss.cn/thumb_large/187633/314834948/stock-photo-head-and-shoulders-portrait-of-a-young-businesswoman-smiling-314834948.jpg",
      "preview_url": "http://thumb109.test-ss.cn/display_pic_with_logo/187633/314834948/stock-photo-head-and-shoulders-portrait-of-a-young-businesswoman-smiling-314834948.jpg"
    },
    {
      "id": "160580261",
      "aspect": 1.5,
      "description": "Beautiful businesswoman outdoor in the city",
      "large_thumb_url": "http://thumb103.test-ss.cn/thumb_large/210376/160580261/stock-photo-beautiful-businesswoman-outdoor-in-the-city-160580261.jpg",
      "preview_url": "http://thumb103.test-ss.cn/display_pic_with_logo/210376/160580261/stock-photo-beautiful-businesswoman-outdoor-in-the-city-160580261.jpg"
    }
  ]
}

我的购买记录

  • 接口地址 image/my-purchases

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
    begin_at false TIMESTAMP 开始时间 例如：2017-01-01 23:23:23
    end_at false TIMESTAMP 结束时间 例如：2017-01-01 23:23:23
    is_download false int 是否下载 默认值全部 1是 2否
    image_id false int 图片ID
    per_page false int 每页数量 默认值 10
    page false int 哪一页 默认值第一页
  • 返回结果
{
  "result": true,
  "data": {
    "per_page": 10, //每页数量
    "total": 1, //总数量
    "list": [
      {
        "id": 35,  //购买ID
        "plus_user": { //购买用户
          "id": 14563341,
          "name": "xxx"
        },
        "real_plus_user": { //真实购买用户
          "id": 14563341,
          "name": "xxxx"
        },
        "third_user_id": "", //第三方用户ID
        "plus_permission": { //购买权限
          "id": 42,
          "name": "图片样片"
        },
        "able_id": 2234622970, //购买资源ID
        "able_type": "image", //购买资源名称
        "asset_type": "medium_jpg", //资源大小
        "warrant_name": "", //授权名称
        "download_at": "2017-02-25 00:32:18", //下载时间
        "created_at": "2017-02-25 00:32:18" // 购买时间
      }
    ]
  }
}

授权书下载

  • 接口地址 image/download-warrant

  • 请求方式 GET

  • 请求参数

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

历史购买再下载

  • 接口地址 image/purchase-download

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
    purchase_id true int 购买ID
  • 返回结果
{
  "result": true,
  "data": {
    "url": "http://download.hellorf.com/hellorf/71/3f/3d23d8a247ff9adfea92c99cb9e4/hellorf_2234622970.jpg" //下载地址
  }
}

购买记录详情

  • 接口地址 image/purchase-detail

  • 请求方式 GET

  • 请求参数

    参数名 必选 类型 说明
    purchase_id true int 购买ID
  • 返回结果
{
  "result" : true,
  "data" : {
    "image" : {
      "id" : "409749292", // 图片ID
      "preview_url" : "https://hellorfimg.zcool.cn/preview/409749292.jpg", // 450px 预览图
      "preview_large_url" : "https://image.shutterstock.com/z/stock-photo-409749292.jpg", // 1000px+ 预览图
      "aspect" : 1.50, // 宽高比
      "title" : "Two businesswoman having an informal meeting", // 标题
      "keywords" : [ // 关键字
        "explain",
        "communicate",
        "conference",
        "occupation",
      ],
      "format" : "JPG", // 图片格式 [EPS, JPG]
      "image_type" : "photo", // 图片类型 [photo, illustration, vector]
      "has_model_release" : true, // 肖像权
      "has_property_release" : true, // 物权
      "category_ids" : [ // 图片分类ID
        "13",
        "4"
      ],
      "created_at" : "2019-05-09 23:57:05" // 图片创建时间
    },
    "purchase" : {
      "id" : 1, // 购买记录ID
      "permission_id" : 27, // 权限ID
      "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" // 购买时间
    }
  }
}

  • 接口地址 image/simi-search

  • 请求方式 POST

  • 请求参数

    参数名 必选 类型 说明
    url false string 图片地址 url和file必须二选一并且图片大小不能大于4M
    file false file 图片源 base64格式 此参数不计入签名
    per_page false int 数量，最大值100
  • 返回结果
{
  "result": true,
  "data": [
    {
      "id": "123692176",
      "aspect": 1.4286,
      "description": "Futuristic background - circle",
      "large_thumb_url": "http://thumb102.test-ss.cn/thumb_large/1088888/123692176/stock-photo-futuristic-background-circle-123692176.jpg",
      "preview_url": "http://thumb102.test-ss.cn/display_pic_with_logo/1088888/123692176/stock-photo-futuristic-background-circle-123692176.jpg",
      "preview260_url": "https://image.shutterstock.com/image-photo/-260nw-734067445.jpg"
    },
    {
      "id": "200879663",
      "aspect": 1,
      "description": "Vector Glossy Sphere. Abstract Background ",
      "large_thumb_url": "http://thumb106.test-ss.cn/thumb_large/922130/200879663/stock-vector-vector-glossy-sphere-abstract-background-200879663.jpg",
      "preview_url": "http://thumb106.test-ss.cn/display_pic_with_logo/922130/200879663/stock-vector-vector-glossy-sphere-abstract-background-200879663.jpg",
      "preview260_url": "https://image.shutterstock.com/image-photo/-260nw-200879663.jpg"
    }
  ]
}