Media API

5 operations. Authentication, errors and pagination work as described in the REST API overview.

Get a media item

GET/api/v1/media/{id}Token optional

The owner sees every status. Others see only ready, scan-clean media attached to something they can read. URLs point at media.incantory.ai.

getMedia parameters
Name	Type	Description
`id` pathrequired	`string`	Media id

Responses: 200 OK304, 400, 404, 429

Response fields

getMedia response fields
Name	Type	Description
`id`required	`string`
`kind`required	`"image" \| "video" \| "file"`
`mime`required	`string`
`bytes`required	`integer (-9007199254740991–9007199254740991)`
`status`required	`"uploading" \| "processing" \| "ready" \| "failed" \| "quarantined"`
`scanStatus`required	`"pending" \| "clean" \| "infected" \| "error" \| null`
`url`required	`string \| null`
`width`required	`integer (-9007199254740991–9007199254740991) \| null`
`height`required	`integer (-9007199254740991–9007199254740991) \| null`
`durationS`required	`number \| null`
`blurhash`required	`string \| null`
`posterUrl`required	`string \| null`
`variants`required	`object[]`
`alt`required	`string \| null`
`filename`required	`string \| null`

Example

curl 'https://incantory.ai/api/v1/media/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Open a resumable upload

POST/api/v1/uploadsToken required

Declares the file (filename, mime, bytes, purpose) and returns a session with partSize and partCount. Limits per purpose: images 20 MB (avatars 5 MB), video mp4/webm 200 MB, files 100 MB. SVG and HTML are refused; types are checked by magic bytes when the bytes arrive. Sessions expire after 24 hours. Session (browser) auth only: API tokens cannot upload media.

Request body

createUpload body fields
Name	Type	Description
`filename`required	`string`
`mime`required	`string`
`bytes`required	`integer (…–2147483647)`
`sha256`	`string`
`purpose`required	`"make" \| "example" \| "post" \| "avatar" \| "prompt_file" \| "make_file"`
`alt`	`string`
`contentRating`	`"general" \| "mature"`

Responses: 201 OK400, 401, 403, 404, 413, 415, 429

Response fields

createUpload response fields
Name	Type	Description
`id`required	`string`
`mediaId`required	`string`
`partSize`required	`integer (-9007199254740991–9007199254740991)`
`partCount`required	`integer (-9007199254740991–9007199254740991)`
`presignedParts`	`object[]`
`expiresAt`required	`string`

Example

curl -X POST 'https://incantory.ai/api/v1/uploads' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"filename":"filename","mime":"mime","bytes":1,"purpose":"make"}'

Cancel an upload

DELETE/api/v1/uploads/{id}Token required

Aborts the multipart upload and discards the stored parts.

abortUpload parameters
Name	Type	Description
`id` pathrequired	`string`	Upload session id (= the media id)

Responses: 204 OK400, 401, 403, 404, 409, 429

Example

curl -X DELETE 'https://incantory.ai/api/v1/uploads/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Finish an upload

POST/api/v1/uploads/{id}/completeToken required

Assembles the parts and returns the MediaView with status processing; the worker makes variants (images/video) and scans it, then status becomes ready (files: only once the malware scan is clean). Idempotent.

completeUpload parameters
Name	Type	Description
`id` pathrequired	`string`	Upload session id (= the media id)

Responses: 200 OK400, 401, 403, 404, 409, 410, 415, 429

Response fields

completeUpload response fields
Name	Type	Description
`id`required	`string`
`kind`required	`"image" \| "video" \| "file"`
`mime`required	`string`
`bytes`required	`integer (-9007199254740991–9007199254740991)`
`status`required	`"uploading" \| "processing" \| "ready" \| "failed" \| "quarantined"`
`scanStatus`required	`"pending" \| "clean" \| "infected" \| "error" \| null`
`url`required	`string \| null`
`width`required	`integer (-9007199254740991–9007199254740991) \| null`
`height`required	`integer (-9007199254740991–9007199254740991) \| null`
`durationS`required	`number \| null`
`blurhash`required	`string \| null`
`posterUrl`required	`string \| null`
`variants`required	`object[]`
`alt`required	`string \| null`
`filename`required	`string \| null`

Example

curl -X POST 'https://incantory.ai/api/v1/uploads/{id}/complete' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Upload one part (raw bytes)

PUT/api/v1/uploads/{id}/parts/{n}Token required

Body: application/octet-stream, exactly partSize bytes except the last part. Re-sending a part number replaces it, so a client resumes by re-sending the parts it is unsure of. Part 1 is magic-byte checked: a mismatching, markup or executable file fails the upload with 415.

uploadPart parameters
Name	Type	Description
`id` pathrequired	`string`	Upload session id
`n` pathrequired	`string`	Part number, 1-based

Responses: 200 OK400, 401, 403, 404, 409, 410, 413, 415, 429

Response fields

uploadPart response fields
Name	Type	Description
`n`required	`integer (-9007199254740991–9007199254740991)`
`size`required	`integer (-9007199254740991–9007199254740991)`
`etag`required	`string`

Example

curl -X PUT 'https://incantory.ai/api/v1/uploads/{id}/parts/{n}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"