Skip to content
aitoken.tools
Sign up

API docs · Assets

Uploading assets

Single-part, multipart and URL import.

Upload assets to the platform first, then reference them by asset_id in the task's inputs; the same asset can be reused across many tasks. Each file can be up to 2 GiB, and an upload session is valid for 1 hour (see the returned expires_at).

Single-part upload

For files up to 100 MB, POST /v1/uploads returns method: "single" and a presigned upload_url. PUT the file body to it with the returned headers, then call complete.

Multipart upload

Larger files return method: "multipart" along with part_size (usually 16.0 MB) and part_count:

  1. Call POST /v1/uploads/{id}/parts with { "part_numbers": [1, 2, …] } (up to 100 per request). It returns { "parts": [{ "part_number": 1, "url": "…" }] }.
  2. Split the file in order, PUT each part, and record the ETag response header.
  3. Call complete with { "parts": [{ "part_number": 1, "etag": "…" }] }.

URL import

Call POST /v1/assets with source_url instead of upload_id and the platform fetches the file from that URL. Only public http / https URLs are supported, the file must be at most 250 MB, and the download must finish within 60 seconds. The asset is only stored permanently once the fetch and save succeed. If the fetch fails, the status becomes failed and status_reason explains why.

Asset statuses

statusMeaning
UploadingURL import: fetching the file
ProcessingThe platform is probing format, dimensions and duration and running content moderation
AvailableReady to use in tasks
Needs authorizationAsset declared as a real person (real_person); real-person authorization is required
FailedUnsupported format, fetch failed, content moderation rejected, or checksum mismatch; see status_reason
DeletingDeletion requested; if in-progress tasks still reference it, it is removed after they finish

Submitting a task before the asset is available returns 422 asset_not_ready (retryable).

# 1. Request an upload
curl https://cn-api.aitoken.tools/v1/uploads \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"hero.png","content_type":"image/png","size_bytes":1832211}'

# 2. PUT the file to the returned upload_url (with the returned headers)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @hero.png

# 3. Complete the upload
curl -X POST https://cn-api.aitoken.tools/v1/uploads/upl_xxx/complete \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

# 4. Create the asset
curl https://cn-api.aitoken.tools/v1/assets \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_xxx","name":"hero"}'