By capability

Upload files

Use the platform file-upload flow when a client only has a local image, video, audio, PDF, spreadsheet, or other file. The API returns a temporary upload destination and a stable public_url; storage implementation details remain opaque to the client.

#Choose URL, upload, or Base64

Input available	Recommended path	Why
Existing public HTTPS URL	Send the URL directly	No duplicate upload and the smallest request body.
Local file on device	Upload, then send public_url	Reliable for large files and reusable across retries.
Small inline image and model explicitly supports Base64	Base64 is acceptable	Use only when the selected model contract allows it.

#Local file upload flow

1
Read the current limit
Use the same API key so user-specific limits are applied.
GET /v1/media/upload-policy
2
Create an upload policy
Send kind, concrete content_type, and exact byte size.
POST /v1/media/upload-policy
3
Upload the file
POST every returned fields entry plus the file to upload_url.
multipart/form-data
4
Use the returned URL
Put public_url into the media field supported by the model.
public_url

create-policy.sh

curl https://www.aisplice.store/v1/media/upload-policy \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "file",
    "content_type": "application/pdf",
    "size": 1048576
  }'

#Treat upload fields as opaque

Send every key and value returned in fields without renaming, filtering, or caching them. The upload policy is short-lived and tied to one generated file path.

browser.ts

const form = new FormData();
for (const [key, value] of Object.entries(policy.fields)) {
  form.append(key, String(value));
}
form.append("file", file); // keep the file field last

const uploaded = await fetch(policy.upload_url, {
  method: "POST",
  body: form,
});
if (!uploaded.ok) throw new Error(await uploaded.text());

const modelInputUrl = policy.public_url;

#File types and model support

Upload success is not model acceptance

The upload endpoint can store generic files such as PDF, Excel, and text, but a model can consume them only when its request contract documents a matching file or URL field. Image-only models cannot read a spreadsheet merely because it has a public URL.

Check the selected model contract

Every field: /v1/media/upload-policy in the API reference →

Still stuck?

Send us the request ID or the error message and we will look into it.

Previous3D models NextIntegration basics