Uploads

Give Dramatis Studio an image in one of three ways: a public HTTPS link, a small file inside the request as a data: address (up to 1 MiB), or an upload. An upload is for a file too large to send inline.

Three calls

1. POST /v1/uploads with the file's type and size. The answer is a ticket: an id, an upload_url, the upload_headers to send and an expires_at. The ticket is valid for 20 minutes.
2. Send the file to upload_url with PUT, with exactly the upload_headers.
3. POST /v1/uploads/{id}/complete. Dramatis Studio checks the file and returns the upload with a reference of the form opsis://upl_….

Using an upload

Use the reference wherever a task takes an image, as often as you need, for 24 hours after completion. An upload belongs to the account that made it. DELETE /v1/uploads/{id} removes it and is never refused, even while a waiting task uses it. If the upload is gone or past its expires_at when the task is built, the task ends FAILED with invalid_asset, refunded.

Namespace

POST /v1/uploads takes an optional namespace, in the same format as a task's: 1 to 128 characters of letters, digits, ., _, = and -, starting with a letter or a digit. See Tasks. The upload returns it as namespace, or null when none was given.

A task may use an upload of its own namespace or an upload with no namespace. A task without a namespace may use only uploads with no namespace. Any other upload is refused when the task is created, as 400 invalid_request with param naming the field.

Limits

• JPEG, PNG or WebP, up to 10 MB. Here "MB" means 1024 × 1024 bytes, so the limit is 10 485 760 bytes.
• The account may hold 100 uploads at a time. A ticket that was not completed counts until it is swept. Beyond that, POST /v1/uploads answers 409 limit_reached.
• An upload of the wrong type or size for the model is refused when the task is created, as 400 invalid_request with param naming the field. It is not a task that fails later.