图片 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==

          > 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	可选	配置小米通道的图片地址；如果您的应用没有通过极光平台开通小米厂商通道，则不对该字段做处理；本接口将会对该地址的图片资源自动进行尺寸的调整和压缩，以适配小米对该图片的要求，其要求具体见参考；若提交的图片资源尺寸不符，则进行等比例缩放且以留白的形式进行调整，而不会对图片进行剪裁；若适配调整失败，将返回错误；建议提交与要求相符的图片资源，小米厂商对该图片要求请参考小米-图片上传。小米从 2023.08 开始，官方在新设备/系统已经不再支持推送时动态设置小图标、右侧图标、大图片功能，对于历史设备和应用也在逐步覆盖，等于不再支持推送时动态设置小图标、右侧图标、大图片功能。
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", // 适配小米要求后小米响应得到的图标地址，小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" // 配置的极光通道的图标地址 }

          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"   // 配置的极光通道的图标地址
}

此代码块在浮窗中显示

失败返回

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 。

注意：小米从 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'

          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 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	可选	配置小米通道的图片地址；如果您的应用没有通过极光平台开通小米厂商通道，则不对该字段做处理；本接口将会对该地址的图片资源自动进行尺寸的调整和压缩，以适配小米对该图片的要求，其要求具体见参考；若提交的图片资源尺寸不符，则进行等比例缩放且以留白的形式进行调整，而不会对图片进行剪裁；若适配调整失败，将返回错误；建议提交与要求相符的图片资源，小米厂商对该图片要求请参考小米-图片上传。小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能，开发者可不在设置此字段值
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

注意：小米从 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'

          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 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 接入文档