Get File Upload Policy

Purpose

Returns a temporary policy for uploading one input file. Request a policy first, then upload the file to response.upload.url using the method specified by response.upload.method. After the upload succeeds, use response.resource_url as the relevant entry in resources when creating an analysis task.

Always check meta.code: 0 indicates business success. The upload policy remains valid for the number of seconds specified by ttl; request a new policy after it expires. Do not save or submit the temporary signed upload.url as the resource URL.

Request fields

Field	Type	Required	Description
`file_name`	string	Conditional	Original file name, for example `front.jpg`. It is used to determine the file type and allocate a resource identifier; do not pass a client-side directory path.
`suffix`	string	Conditional	File extension without the leading dot, for example `jpg`. When only this field is provided, the service generates a file name.

Provide at least one of file_name and suffix. If only file_name is supplied, its extension is used. ZIP files are currently not supported.

Response fields

Field	Type	Description
`meta.code`	integer	Business status code. `0` indicates success.
`meta.msg`	string	Business message.
`meta.error`	string	Error details; empty on success.
`meta.req_id`	string	Request identifier for troubleshooting.
`meta.request_uri`	string	Current request path.
`response.resource_key`	string	Allocated file resource identifier.
`response.resource_url`	string	Resource URL to use after the upload succeeds. Submit this URL when creating an analysis task.
`response.ttl`	integer	Upload policy validity period in seconds.
`response.upload.method`	string	Upload method. The current values are `PUT` and `POST`.
`response.upload.url`	string	Destination for this upload; use it only while the policy is valid.
`response.upload.form_data`	object	Form fields that must be sent unchanged for a `POST multipart/form-data` upload.
`response.provider`	string	Upload service identifier, when returned.
`response.token`	string	Upload credential, when returned.
`response.hosts`	object	Available upload host information, when returned.
`response.mime`	string	File MIME type, when returned.

Upload flow

Call this endpoint and confirm that meta.code = 0.

Branch on response.upload.method; clients must not assume a single upload method.

Upload the file before response.ttl expires.

After the upload request succeeds, retain response.resource_url.

When creating an analysis task, put that URL in the appropriate image or file entry under resources.

`PUT` upload

Send the raw file bytes as the request body. Do not wrap them in multipart form data. Example:

`POST multipart/form-data` upload

Add every field from response.upload.form_data to the form unchanged, then add the file itself as a form field named file. Example:

Use the form field names and values exactly as returned; do not rename, omit, or recalculate them.

Create an analysis task after upload

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

Common business error codes

`meta.code`	Meaning	Resolution
`44007`	File name is missing	Provide `file_name` or `suffix`.
`44008`	The file extension cannot be determined	Provide `suffix`, or supply `file_name` with an extension.
`44053`	Unsupported file type	Use a supported file type. ZIP is currently not supported.
`44098`	Invalid merchant information	Check the calling credential and merchant configuration.
`44099`	The request region does not match the merchant region	Retry through the API base URL for the merchant's region.

Purpose#

Request fields#

Response fields#

Upload flow#

PUT upload#

POST multipart/form-data upload#

Create an analysis task after upload#

Common business error codes#

Request

Responses