Developer docs / File upload
Create a presigned upload
Submit file metadata and the compatible hash to receive a fileId and object-storage URL. Skip upload and confirmation when isNew is false.
POST
/v1/file/presign- Authentication:
- Request header x-api-key: <YOUR_API_KEY>; keep the key on the server and never expose it in client code, logs or shared files.
- Success criteria:
- HTTP 2xx with code=0; for asynchronous tasks, also query the final status.
Request body fields
| Field | Type | Required | Description |
|---|---|---|---|
fileName | string | Yes | File name including extension |
contentType | string | Yes | File MIME type |
size | integer | Yes | File size in bytes |
hash | string | Yes | SHA-256 of the UTF-8 encoded lowercase hex representation of the file bytes |
When isNew is true, PUT the raw file to uploadUrl with the same Content-Type, then call confirm.
Do not send x-api-key to the object-storage PUT URL.
Request body
{
"fileName": "video.mp4",
"contentType": "video/mp4",
"size": 12345678,
"hash": "3786a02b..."
}Success response
{
"code": 0,
"data": {
"fileId": 591,
"uploadUrl": "https://object-storage.example.com/presigned-url",
"url": "https://cdn.ailingtu.com/media/video.mp4",
"isNew": true,
"expiresAt": "2026-07-29T12:00:00Z"
},
"message": "success"
}Response and errors
Main response fields come from the published contract; see the JSON Schema. Required refers to the constraint in the containing object.
| Field | Type | Required | Description |
|---|---|---|---|
code | integer | Yes | Fixed value: 0 |
message | string | No | — |
data | object | Yes | — |
data.fileId | union | Yes | — |
data.uploadUrl | string | null | No | — |
data.url | string | Yes | — |
data.isNew | boolean | Yes | — |
data.expiresAt | string | null | No | — |
HTTP 400The request parameters or body are invalid. Fix them and retry.HTTP 401The API key is missing or invalid. Check x-api-key.HTTP 403The API key has no permission to call this endpoint.HTTP 429Too many requests. Retry with exponential backoff.HTTP 500The server failed. Retry transient failures with exponential backoff.
Fix parameter, permission or authorization errors before retrying. If task creation times out, query existing tasks first and do not submit duplicates after an interrupted poll.
Last updated · 2026-11-16