文档中心

veImageX

数据抓取

本接口通过指定一个公网可访问的待迁移资源 URL 以及上传目标服务 ID 等信息，来对资源进行抓取和上传，并得到迁移后的资源存储 URI 等信息。

说明

如果您的数据在本地 IDC 或者在本地磁盘中，同时通过本地服务器挂载云存储的资源迁移 veImageX 存储，推荐您使用本地迁移与上传工具进行数据迁移。
如果您的数据位于第三方云厂商或有可公网访问的 URL 本地数据，您可以登录 veImageX 使用数据迁移功能迁移您的数据至 veImageX 存储。

注意事项

请求频率限制：同步处理情况下，请求频率限制为 100 次/秒。
超时时间：约为 20 秒。
同步处理：
- 若迁移资源 URL 支持分片下载，最大超时时间为 20 s，最大迁移资源不超过 5 G；
- 若迁移资源 URL 不支持分片下载，最大超时时间为 20 s，最大迁移资源不超过 1 G。
异步处理：
若迁移资源 URL 不支持分片下载，最大超时时间为 90 s，最大迁移资源不超过 5 G。
说明
- 以上数据为我们内部实验环境得出，仅供参考，具体情况请以您实际网络环境为准。
- 请您自行配置待迁移资源 Url 是否需要支持分片下载。
服务地址：veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。具体详情请查看服务地址。

请求说明

请求方式：POST
请求地址：https://imagex.volcengineapi.com/?Action=FetchImageUrl&Version=2023-05-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`FetchImageUrl`	接口名称。当前 API 的名称为 `FetchImageUrl`。
Version	String	是	`2023-05-01`	接口版本。当前 API 的版本为 `2023-05-01`。

Body

参数	类型	是否必选	示例值	描述
Url	String	是	`https://test.org/con.jpg`	待抓取上传的文件 URL。
ServiceId	String	是	`jh**9k`	目标服务 ID，迁移后的文件将上传至该服务绑定的存储。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。
StoreKey	String	否	`FetchTest`	指定抓取成功后的文件存储 key，不包含 bucket 部分。默认使用随机生成的 key。说明若指定 key 已存在，则会覆盖服务中 StoreKey 对应的已有文件，此时服务中保存文件的数量未发生变化。
RequestHeader	JSON Map	否	`{ "X-Function-Id": ["test"] }`	请求 header
TimeOut	Integer	否	`10`	资源下载超时时间。同步处理下最大超时为 20 秒；异步处理下最大超时为 90 秒。说明若待迁移的资源首包响应过慢，则迁移任务可能会提前超时。
Async	Boolean	否	`false`	是否采用异步，取值如下所示： `true`：采用异步 `false`：（默认）不采用异步说明若您的资源大小小于 5 G，但预估资源迁移超时时间超过 20 s，建议您选择异步处理。
Host	String	否	`ip:port`	迁移资源的 IP 地址
Callback	String	否	`https://info.com`	回调 URL，veImageX 以 Post 方式向业务服务器发送 JSON 格式回调数据。当`Async`取值为`true`，即采用异步处理时，为必填。
MD5	String	否	`9a8229123604d22d18b6dcfe44b4519e`	校验下载文件的 MD5，若校验不一致则停止文件的上传。
CallbackBodyType	String	否	`application/json`	透传给业务的回调内容格式。当`CallbackBody`不为空时为必填。取值如下所示： `application/json` `application/x-www-form-urlencoded`
CallbackBody	String	否	`{ "param1": "value1", "param2": "value2" }`	透传给业务的回调内容，当`Callback`不为空时为必填，取值需要符合`CallbackBodyType`指定格式。
CallbackHost	String	否	`ip:port`	回调时使用的 IP 地址
IgnoreSameKey	Boolean	否	`false`	服务存储中存在相同的存储 key 时，是否忽略本次迁移操作。取值如下所示： `true`：忽略本次迁移操作。 `false`：（默认）继续迁移并覆盖相同 key 的资源。
FetchOnly	Boolean	否	`true`	是否仅迁移文件，取值如下所示： `true`：仅将文件迁移至目标服务对应的存储。适用于文件快速迁移且无需获取图片元信息场景，例如对时间敏感度极高的文件传输任务。 `false`：（默认）迁移文件的同时，对图片类文件进行解码处理。适用于需要获取图片元信息而对迁移时间要求不高的场景。解码图片资源后，您可在返回参数获取图片的元信息，包括图片宽高、图片类型、动图的时间和帧数等，便于后续的图片分析和管理。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数	类型	示例值	描述
Url	String	`https://test.org/con.jpg`	源文件 URL
StoreUri	String	`tos-boe-i-241*mp8/32f6b311fa`	迁移后的文件 URI，包含 bucket/key 两部分。
FSize	Long	`9084`	文件大小，单位为 byte。同步处理情况下有返回值。
ImageWidth	Integer	`2300`	图片宽，在同步处理情况下、迁移至图像处理服务且为图片资源时有返回值。
ImageHeight	Integer	`1100`	图片高，在同步处理情况下、迁移至图像处理服务且为图片资源时有返回值。
ImageFormat	String	`png`	图片类型，在同步处理情况下、迁移至图像处理服务且为图片资源时有返回值。
Duration	Long	`5`	动图持续时间，在同步处理情况下、迁移至图像处理服务且为图片资源时有返回值。
FrameCnt	Integer	`100`	图片帧数，在同步处理情况下、迁移至图像处理服务且为图片资源时有返回值。
TaskId	String	`92830H07WJS28370`	异步任务 ID，仅当`Async`取值`true`，即采用异步时有返回值。
StartTime	Long	`1692019200000000000`	任务开始执行时间戳，UTC 时间，单位为 ns。
EndTime	Long	`1689304215000000000`	任务结束执行时间戳，UTC 时间，单位为 ns。
TimeCost	Long	`2714985000`	完成任务总耗时，单位为毫秒。

请求示例

POST https://imagex.volcengineapi.com/?Action=FetchImageUrl&Version=2023-05-01
{
    "Url": "https://test.org/con.jpg",
    "ServiceId": "jh**9"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "FetchImageUrl",
        "Version": "2023-05-01",
        "Service": "ImageX",
        "Region": "cn-north-1"
    },
    "Result": {
        "Url": "https://test.org/con.jpg",
        "StoreUri": "tos-cn-i-241**mp8/32f6b311fa*",
        "EndTime": 1689304215000000000,
        "StartTime": 1692019200000000000,
        "TimeCost": 2714985000
    }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码以及 veImageX 错误码。

服务端 SDK

为了方便您快速开发，veImageX 提供了配套的服务端 SDK，同时支持多种编程语言。建议您使用服务端 SDK 来调用 API，参考文档如下所示：

历史版本

2018-08-01 版本 FetchImageUrl 接口文档现已停止维护，建议您参考本文档使用最新版本。

最近更新时间：2025.04.11 16:36:54

这个页面对您有帮助吗？

有用

无用

veImageX

注意事项 #

请求说明 #

请求参数 #

Query #

Body #

返回参数 #

请求示例 #

返回示例 #

错误码 #

服务端 SDK #

历史版本 #