图片 API
最近更新:2022-07-22
展开全部
图片 API
概述
功能说明
需要结合Push Android SDK v3.9.0及其以上版本配套使用。开发者提交图片或者网络资源 URL 至极光服务器,极光会根据开发者需求对接适配各个厂商,同时开发者将从极光得到对应资源的MediaID,该MediaID可于 Push API v3 中使用,达到统一推送大图片、大图标和小图标的需求。
调用地址
https://api.jpush.cn/v3/images
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
调用限制
- 上传图片大小不超过 2M
- 图片默认最多保存30天(从 2023-08-31 号开始实施,请开发者关注)
- API 请求频率限制与 Push API v3 接口共享
各通道支持及要求情况
- 该接口可适配的厂商通道有:极光、小米、OPPO、华为、荣耀以及FCM;
- 目前该接口暂不提供存储文件服务,故请确保提交的图片资源可被访问且符合要求;
- 不同通道对不同类型的图片支持情况不同,具体如下表格所示:
极光通道 小米 OPPO 华为 荣耀 FCM 大图片 1. 支持http
2. 支持https
3. 支持本地资源路径,且必须是sdcard的相对路径,需要指定文件后缀
1. 支持http
2. 支持https
3. 暂不支持小米国际版适配
1. 支持http
2. 支持https
- - 1. 支持http
2. 支持https
3. 支持本地资源路径,且必须是sdcard的相对路径,需要指定文件后缀
大图标 1. 支持http
2. 支持https
3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
1. 支持http
2. 支持https
1. 支持http
2. 支持https
1. 支持https
1. 支持https
1. 支持http
2. 支持https
3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
小图标 1. 支持http
2. 支持https
3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
1. 支持http
2. 支持https
- 1. 支持本地资源路径,且必须提交以 /raw/ 开头的路径,无需指定文件后缀 1. 支持本地资源路径,且必须提交以 /raw/ 开头的路径,无需指定文件后缀 -
备注:以上都仅支持 jpg 、 jpeg 以及 png 格式的资源。
新增图片(URL方式)
调用地址
POST https://api.jpush.cn/v3/images/byurls
功能说明
通过指定网络图片资源的URL形式来新增一个适配
调用示例
请求报头
> POST /v3/images/byurls HTTP/1.1
> Content-Type: application/json
> Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==
> POST /v3/images/byurls HTTP/1.1
> Content-Type: application/json
> Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==
此代码块在浮窗中显示
请求数据
{
"image_type": 2,
"image_url": "https://xx.com/xx.jpg",
"oppo_image_url": "https://xx.com/oppo.jpg",
"xiaomi_image_url": "https://xx.com/xiaomi.jpg",
"huawei_image_url": "",
"honor_image_url": "",
"fcm_image_url": "",
"jiguang_image_url": "https://xx.com/jiguang.jpg"
}
{
"image_type": 2,
"image_url": "https://xx.com/xx.jpg",
"oppo_image_url": "https://xx.com/oppo.jpg",
"xiaomi_image_url": "https://xx.com/xiaomi.jpg",
"huawei_image_url": "",
"honor_image_url": "",
"fcm_image_url": "",
"jiguang_image_url": "https://xx.com/jiguang.jpg"
}
此代码块在浮窗中显示
完整的参数说明如下:
关键字 | 选项 | 含义 |
---|---|---|
image_type | 必填 | 指定适配的图片类型:1大图片-2大图标-3小图标 |
image_url | 可选 |
公共的图片地址; 如果设置了该字段,则当其他字段不设置值时,将该字段的内容作为其他字段的默认值; 例如:仅该字段以及极光字段有值,而小米、OPPO字段无值,则小米、OPPO字段值将被设置成与该字段值相同,但不会改变极光字段值。 |
jiguang_image_url | 可选 | 配置极光通道的图片地址 |
xiaomi_image_url | 可选 |
配置小米通道的图片地址; 如果您的应用没有通过极光平台开通小米厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配小米对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,小米厂商对该图片要求请参考 小米-图片上传。 |
oppo_image_url | 可选 |
配置适配OPPO通道的图片地址; 如果您的应用没有通过极光平台开通OPPO厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配 OPPO 对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,OPPO 厂商对该图片要求请参考 OPPO-图片上传。 |
huawei_image_url | 可选 |
配置华为通道的图片地址; 如果您的应用没有通过极光平台开通华为厂商通道,则不对该字段做处理。 |
honor_image_url | 可选 |
配置荣耀通道的图片地址; 如果您的应用没有通过极光平台开通荣耀厂商通道,则不对该字段做处理。 |
fcm_image_url | 可选 |
配置 FCM 通道的图片地址; 如果您的应用没有通过极光平台开通 FCM 厂商通道,则不对该字段做处理。 |
备注:
image_url
以及各通道的字段值不能同时为空;- 指定的厂商图片字段,仅在厂商支持相应图片类型的情况下被处理;如配置了华为厂商的大图片地址,由于华为厂商不支持大图片类型,则结果中华为字段将为空值。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", // 得到的结果 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "https://xx.com/xx.jpg", // 配置的华为图标地址
"honor_image_url": "https://xx.com/xx.jpg", // 配置的荣耀图标地址
"fcm_image_url": "https://xx.com/xx.jpg", // 配置的FCM图标地址
"jiguang_image_url": "https://xx.com/jiguang.jpg" // 配置的极光通道的图标地址
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", // 得到的结果 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "https://xx.com/xx.jpg", // 配置的华为图标地址
"honor_image_url": "https://xx.com/xx.jpg", // 配置的荣耀图标地址
"fcm_image_url": "https://xx.com/xx.jpg", // 配置的FCM图标地址
"jiguang_image_url": "https://xx.com/jiguang.jpg" // 配置的极光通道的图标地址
}
此代码块在浮窗中显示
失败返回
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
此代码块在浮窗中显示
新增图片(文件方式)
调用地址
POST https://api.jpush.cn/v3/images/byfiles
功能说明
通过上传图片文件形式来新增一个适配,该接口目前仅支持小米和 OPPO 。
调用示例
curl --request POST 'https://api.jpush.cn/v3/images/byfiles' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==' --form 'xiaomi_file=@/home/user/pictures/test_file1.jpg' --form 'oppo_file=@/home/user/pictures/test_file2.jpg' --form 'image_type=1'
curl --request POST 'https://api.jpush.cn/v3/images/byfiles' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==' --form 'xiaomi_file=@/home/user/pictures/test_file1.jpg' --form 'oppo_file=@/home/user/pictures/test_file2.jpg' --form 'image_type=1'
此代码块在浮窗中显示
完整的参数说明如下:
关键字 | 选项 | 含义 |
---|---|---|
image_type | 必填 | 指定适配的图片类型:1大图片-2大图标-3小图标 |
oppo_file | 可选 |
上传配置OPPO通道的图片文件; 本接口将会对该图片文件大小进行校验,若不适配 OPPO 对该图片的要求,则返回错误,OPPO 对该图片对要求参考 OPPO-图片上传。 |
xiaomi_file | 可选 |
上传配置小米通道的图片文件 本接口将会对该图片文件大小进行校验,若不适配小米对该图片的要求,则返回错误,小米对该图片对要求参考 小米-图片上传。 |
备注:oppo_file
和xiaomi_file
不能同时为空。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3", // 得到的结果 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "",
"honor_image_url": "",
"fcm_image_url": "",
"jiguang_image_url": ""
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3", // 得到的结果 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "",
"honor_image_url": "",
"fcm_image_url": "",
"jiguang_image_url": ""
}
此代码块在浮窗中显示
失败返回
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
此代码块在浮窗中显示
更新图片(URL方式)
调用地址
PUT https://api.jpush.cn/v3/images/byurls/{mediaId}
功能说明
通过指定网络图片资源的URL形式来修改/更新适配结果
调用示例
请求报头
> PUT /v3/images/byurls/jgmedia-2-14b23451-0001-41ce-89d9-987b465122da HTTP/1.1
> Content-Type: application/json
> Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==
> PUT /v3/images/byurls/jgmedia-2-14b23451-0001-41ce-89d9-987b465122da HTTP/1.1
> Content-Type: application/json
> Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==
此代码块在浮窗中显示
请求数据
{
"oppo_image_url": "",
"xiaomi_image_url": "",
"huawei_image_url": "https://xx.com/new_huawei.jpg",
"honor_image_url": "https://xx.com/new_honor.jpg",
"fcm_image_url": "",
"jiguang_image_url": "http://xx.com/new_jiguang.jpg"
}
{
"oppo_image_url": "",
"xiaomi_image_url": "",
"huawei_image_url": "https://xx.com/new_huawei.jpg",
"honor_image_url": "https://xx.com/new_honor.jpg",
"fcm_image_url": "",
"jiguang_image_url": "http://xx.com/new_jiguang.jpg"
}
此代码块在浮窗中显示
完整的参数说明如下:
关键字 | 选项 | 含义 |
---|---|---|
jiguang_image_url | 可选 | 更新配置极光通道的图片地址 |
xiaomi_image_url | 可选 |
配置小米通道的图片地址; 如果您的应用没有通过极光平台开通小米厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配小米对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,小米厂商对该图片要求请参考 小米-图片上传。 |
oppo_image_url | 可选 |
配置适配OPPO通道的图片地址; 如果您的应用没有通过极光平台开通OPPO厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配 OPPO 对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,OPPO 厂商对该图片要求请参考 OPPO-图片上传。 |
huawei_image_url | 可选 |
配置华为通道的图片地址; 如果您的应用没有通过极光平台开通华为厂商通道,则不对该字段做处理。 |
honor_image_url | 可选 |
配置荣耀通道的图片地址; 如果您的应用没有通过极光平台开通荣耀厂商通道,则不对该字段做处理。 |
fcm_image_url | 可选 |
配置 FCM 通道的图片地址; 如果您的应用没有通过极光平台开通 FCM 厂商通道,则不对该字段做处理。 |
备注:
- 各通道的字段值不能同时为空;
- 若未指定更新配置的厂商地址,则该厂商的配置结果保留更新前的值而不会被置空,如该接口例子中的小米通道;
- 若指定更新配置的厂商不支持对应类型,则该厂商的配置结果将保留更新前的值而不会被覆盖。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", // 更新的 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "https://xx.com/new_huawei.jpg", // 配置的华为图标地址
"honor_image_url": "https://xx.com/new_honor.jpg", // 配置的荣耀图标地址
"fcm_image_url": "https://xx.com/xx.jpg", // 配置的FCM图标地址
"jiguang_image_url": "http://xx.com/new_jiguang.jpg" // 配置的极光通道的图标地址
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", // 更新的 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "https://xx.com/new_huawei.jpg", // 配置的华为图标地址
"honor_image_url": "https://xx.com/new_honor.jpg", // 配置的荣耀图标地址
"fcm_image_url": "https://xx.com/xx.jpg", // 配置的FCM图标地址
"jiguang_image_url": "http://xx.com/new_jiguang.jpg" // 配置的极光通道的图标地址
}
此代码块在浮窗中显示
失败返回
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
此代码块在浮窗中显示
更新图片(文件方式)
调用地址
PUT https://api.jpush.cn/v3/images/byfiles/{mediaId}
功能说明
通过上传图片文件形式来修改/更新适配结果,该接口目前仅支持小米和 OPPO
调用示例
curl --request PUT 'https://api.jpush.cn/v3/images/byfiles/jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==' --form 'xiaomi_file=@/home/user/pictures/test_file1.jpg' --form 'oppo_file=@/home/user/pictures/test_file2.jpg'
curl --request PUT 'https://api.jpush.cn/v3/images/byfiles/jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==' --form 'xiaomi_file=@/home/user/pictures/test_file1.jpg' --form 'oppo_file=@/home/user/pictures/test_file2.jpg'
此代码块在浮窗中显示
完整的参数说明如下:
关键字 | 选项 | 含义 |
---|---|---|
oppo_file | 可选 |
上传配置OPPO通道的图片文件; 本接口将会对该图片文件大小进行校验,若不适配 OPPO 对该图片的要求,则返回错误,OPPO 对该图片对要求参考 OPPO-图片上传。 |
xiaomi_file | 可选 |
上传配置小米通道的图片文件 本接口将会对该图片文件大小进行校验,若不适配小米对该图片的要求,则返回错误,小米对该图片对要求参考 小米-图片上传。 |
备注:oppo_file
和xiaomi_file
不能同时为空
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3", // 更新的 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_3_5f9a5f7cb3c87bf699b332a5", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f8.market.xiaomi.com/download/MiPass/0dfdb5eba1bbb8d1671983fdb2be94074ec/8a350da36d46835768f17f48a6b12b2765cec115.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "",
"honor_image_url": "",
"fcm_image_url": "",
"jiguang_image_url": ""
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"media_id": "jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3", // 更新的 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
"oppo_image_url": "3653918_3_5f9a5f7cb3c87bf699b332a5", // 适配 OPPO 要求后 OPPO 响应得到的 id
"xiaomi_image_url": "http://f8.market.xiaomi.com/download/MiPass/0dfdb5eba1bbb8d1671983fdb2be94074ec/8a350da36d46835768f17f48a6b12b2765cec115.png", // 适配小米要求后小米响应得到的图标地址
"huawei_image_url": "",
"honor_image_url": "",
"fcm_image_url": "",
"jiguang_image_url": ""
}
此代码块在浮窗中显示
失败返回
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error": {
"code": 1002,
"message": "Missing authen info."
}
}
此代码块在浮窗中显示
状态码说明
Code | 描述 | 详细解释 | HTTP Status Code |
---|---|---|---|
1000 | 系统内部错误 | 服务器端内部逻辑错误,请稍后重试 | 500 |
1002 | 验证失败 | 缺少Authorization信息 | 400 |
1004 | 验证失败 |
1. Authorization中的token格式错误 2. appkey无效 3. appkey与masterSecret不匹配 |
401 |
1102 | 缺少必要参数 | 缺少必要参数 | 400 |
1103 | 参数值不合法 |
1. 上传文件太大 2. 文件格式不正确 3. 提交的 mediaId 无效 4. OPPO 上传图片数量超过了每天限制,限制数量为:大图每天最多上传 100 张,大图标每天最多上传 500 张,详情参考 OPPO 官网说明。 5. “the result is all of invalid”请检查是否开通配置了对应的厂商通道及图片类型是否支持 6. 其他错误 |
400 |
1030 | 服务超时 |
1. 服务内部调用超时 2. 图片适配厂商响应超时 |
503 |
参考
- HTTP 返回码:HTTP-Status-Code
- HTTP 规范参考:HTTP 基本认证
- 推送Push API:Push API v3
- OPPO图片要求说明:OPPO-图片上传
- 小米图片要求说明:小米-图片上传
- 华为下行消息图片说明:华为-下行消息
- 荣耀消息图片说明:荣耀 API 接入文档
文档内容是否对您有帮助?