获取文件上传策略

接口用途

获取一次性文件上传策略。调用方先请求本接口，再根据 response.upload.method 将文件上传到 response.upload.url。文件上传成功后，使用 response.resource_url 作为创建分析任务接口 resources 中对应资源字段的值。

必须检查 meta.code：0 表示业务成功。上传策略在 ttl 指定的秒数内有效，过期后请重新申请。不要把含临时签名的 upload.url 当作资源地址保存或提交给分析接口。

请求字段

字段	类型	必填	说明
`file_name`	string	条件必填	原始文件名，例如 `front.jpg`。仅用于确定文件类型和生成资源标识，不应传客户端目录。
`suffix`	string	条件必填	不带点的文件扩展名，例如 `jpg`。只传该字段时，服务端生成文件名。

file_name 与 suffix 至少提供一个。只传 file_name 时从文件名提取扩展名；当前不支持 ZIP 文件。

响应字段

字段	类型	说明
`meta.code`	integer	业务状态码，`0` 表示成功。
`meta.msg`	string	业务消息。
`meta.error`	string	错误详情；成功时为空字符串。
`meta.req_id`	string	请求标识，可用于问题追踪。
`meta.request_uri`	string	当前请求路径。
`response.resource_key`	string	已分配的文件资源标识。
`response.resource_url`	string	上传成功后的文件资源 URL；后续创建分析任务时使用此值。
`response.ttl`	integer	上传策略有效期，单位为秒。
`response.upload.method`	string	上传方法，当前可能为 `PUT` 或 `POST`。
`response.upload.url`	string	本次文件上传地址，仅在策略有效期内使用。
`response.upload.form_data`	object	`POST multipart/form-data` 上传时必须原样携带的表单字段。
`response.provider`	string	上传服务标识；仅在返回时使用。
`response.token`	string	上传凭证；仅在返回时使用。
`response.hosts`	object	可用上传地址信息；仅在返回时使用。
`response.mime`	string	文件 MIME 类型；仅在返回时使用。

上传流程

调用本接口并确认 meta.code = 0。

读取 response.upload.method，不要固定只支持一种上传方式。

在 response.ttl 有效期内上传文件。

上传请求成功后，保存 response.resource_url。

创建分析任务时，将该 URL 填入 resources 中对应的图片或文件字段。

`PUT` 上传

请求体必须是文件原始二进制，不要使用 multipart 包装。示例：

`POST multipart/form-data` 上传

将 response.upload.form_data 中的每个字段原样加入表单，并额外添加名为 file 的文件字段。示例：

表单字段以接口实际返回为准，不要自行改名、遗漏或重新计算。

上传完成后创建分析任务

{
  "api_code": "online_skin",
  "algorithm_variant": "standard",
  "resources": {
    "front_image": "https://storage.example.com/files/6d83a0f1-front.jpg"
  }
}

常见业务错误码

`meta.code`	含义	处理方式
`44007`	缺少文件名	提供 `file_name` 或 `suffix`。
`44008`	无法确定文件扩展名	提供 `suffix`，或传入带扩展名的 `file_name`。
`44053`	不支持的文件类型	更换为支持的文件类型；当前不支持 ZIP。
`44098`	商家信息无效	检查调用凭证及商家配置。
`44099`	请求区域与商家区域不一致	使用商家所属区域的 API 地址重新请求。

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200

application/json

HTTP 请求已处理。请检查 meta.code；0 表示业务成功。

Bodyapplication/json

示例

获取成功 - PUT 上传获取成功 - POST 表单上传缺少文件名或扩展名

使用 upload.url 上传文件；上传成功后保存 resource_url。

{
  "meta": {
    "code": 0,
    "msg": "",
    "error": "",
    "req_id": "4826bbfa2ab1db905e6ac2909682746a",
    "request_uri": "/skin_api/file/upload_policy"
  },
  "response": {
    "resource_key": "6d83a0f1-1f6c-4e1a-a5ba-3fb8f4fb8350.jpg",
    "resource_url": "https://storage.example.com/files/6d83a0f1-1f6c-4e1a-a5ba-3fb8f4fb8350.jpg",
    "ttl": 3600,
    "upload": {
      "method": "PUT",
      "url": "https://storage.example.com/files/6d83a0f1-1f6c-4e1a-a5ba-3fb8f4fb8350.jpg?temporary-signature=REDACTED"
    }
  }
}

接口用途#

请求字段#

响应字段#

上传流程#

PUT 上传#

POST multipart/form-data 上传#

上传完成后创建分析任务#

常见业务错误码#

请求参数