图片 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;
- 小米从 2023.08 开始,官方在新设备/系统已经不再支持推送时动态设置小图标、右侧图标、大图片功能,对于历史设备和应用也在逐步覆盖,等于不再支持推送时动态设置小图标、右侧图标、大图片功能;
- 目前该接口暂不提供存储文件服务,故请确保提交的图片资源可被访问且符合要求;
- 不同通道对不同类型的图片支持情况不同,具体如下表格所示:
极光通道 小米 OPPO 华为 荣耀 FCM 大图片 1. 支持http
2. 支持https
3. 支持本地资源路径,且必须是sdcard的相对路径,需要指定文件后缀
- 1. 支持http
2. 支持https
- - 1. 支持http
2. 支持https
3. 支持本地资源路径,且必须是sdcard的相对路径,需要指定文件后缀
大图标 1. 支持http
2. 支持https
3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
- 1. 支持http
2. 支持https
1. 支持https
1. 支持https
1. 支持http
2. 支持https
3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
小图标 1. 支持http
2. 支持https
3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
- - 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==
请求数据
{
"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",
"hmos_image_url": "https://xx.com/hmos.jpg" // 20240813新增,适配鸿蒙上传图片
}
完整的参数说明如下:
关键字 | 选项 | 含义 |
---|---|---|
image_type | 必填 | 指定适配的图片类型:1大图片-2大图标-3小图标 |
image_url | 可选 |
公共的图片地址; 如果设置了该字段,则当其他字段不设置值时,将该字段的内容作为其他字段的默认值; 例如:仅该字段以及极光字段有值,而小米、OPPO字段无值,则小米、OPPO字段值将被设置成与该字段值相同,但不会改变极光字段值。 |
jiguang_image_url | 可选 | 配置极光通道的图片地址 |
xiaomi_image_url | 可选 |
配置小米通道的图片地址; 如果您的应用没有通过极光平台开通小米厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配小米对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,小米厂商对该图片要求请参考 小米-图片上传。 小米从 2023.08 开始,官方在新设备/系统已经不再支持推送时动态设置小图标、右侧图标、大图片功能,对于历史设备和应用也在逐步覆盖,等于不再支持推送时动态设置小图标、右侧图标、大图片功能。 |
oppo_image_url | 可选 |
配置适配OPPO通道的图片地址; 如果您的应用没有通过极光平台开通OPPO厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配 OPPO 对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,OPPO 厂商对该图片要求请参考 OPPO-图片上传。 |
huawei_image_url | 可选 |
配置华为通道的图片地址; 如果您的应用没有通过极光平台开通华为厂商通道,则不对该字段做处理。 |
honor_image_url | 可选 |
配置荣耀通道的图片地址; 如果您的应用没有通过极光平台开通荣耀厂商通道,则不对该字段做处理。 |
fcm_image_url | 可选 |
配置 FCM 通道的图片地址; 如果您的应用没有通过极光平台开通 FCM 厂商通道,则不对该字段做处理。 |
hmos_image_url | 可选 |
配置鸿蒙厂商的图片地址; 如果您的应用没有通过极光平台开通鸿蒙厂商,则不对该字段做处理。 |
备注:
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", // 适配小米要求后小米响应得到的图标地址,小2023.08 开始不再支持
"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", // 配置的极光通道的图标地址
"hmos_image_url": "https://xx.com/xx.jpg" // 配置的鸿蒙图标地址,20240813新增
}
失败返回
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 。
注意:小米从 2023.08 开始,官方在新设备/系统已经不再支持推送时动态设置小图标、右侧图标、大图片功能,对于历史设备和应用也在逐步覆盖,等于不再支持推送时动态设置小图标、右侧图标、大图片功能。
调用示例
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 | 可选 |
上传配置小米通道的图片文件 本接口将会对该图片文件大小进行校验,若不适配小米对该图片的要求,则返回错误,小米对该图片对要求参考 小米-图片上传。 小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能,开发者可不在设置此字段值。 |
备注: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 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==
请求数据
{
"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",
"hmos_image_url": "https://xx.com/hmos.jpg" // 适配鸿蒙更新图片,20240813新增
}
完整的参数说明如下:
关键字 | 选项 | 含义 |
---|---|---|
jiguang_image_url | 可选 | 更新配置极光通道的图片地址 |
xiaomi_image_url | 可选 |
配置小米通道的图片地址; 如果您的应用没有通过极光平台开通小米厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配小米对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,小米厂商对该图片要求请参考 小米-图片上传。 小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能,开发者可不在设置此字段值 |
oppo_image_url | 可选 |
配置适配OPPO通道的图片地址; 如果您的应用没有通过极光平台开通OPPO厂商通道,则不对该字段做处理; 本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配 OPPO 对该图片的要求,其要求具体见参考; 若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,OPPO 厂商对该图片要求请参考 OPPO-图片上传。 |
huawei_image_url | 可选 |
配置华为通道的图片地址; 如果您的应用没有通过极光平台开通华为厂商通道,则不对该字段做处理。 |
honor_image_url | 可选 |
配置荣耀通道的图片地址; 如果您的应用没有通过极光平台开通荣耀厂商通道,则不对该字段做处理。 |
fcm_image_url | 可选 |
配置 FCM 通道的图片地址; 如果您的应用没有通过极光平台开通 FCM 厂商通道,则不对该字段做处理。 |
hmos_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/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", // 配置的极光通道的图标地址
"hmos_image_url": "http://xx.com/new_hmos.jpg" // 配置的鸿蒙通道的图标地址,20240813新增
}
失败返回
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
注意:小米从 2023.08 开始,官方在新设备/系统已经不再支持推送时动态设置小图标、右侧图标、大图片功能,对于历史设备和应用也在逐步覆盖,等于不再支持推送时动态设置小图标、右侧图标、大图片功能。
调用示例
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 | 可选 |
上传配置小米通道的图片文件 本接口将会对该图片文件大小进行校验,若不适配小米对该图片的要求,则返回错误,小米对该图片对要求参考 小米-图片上传。 小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能,开发者可不在设置此字段值。 |
备注: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 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 接入文档