Media library

Media library endpoints of the Zanfia Workspace API, with schemas and code samples.

7 min readLast updated Sep 10, 2026

Upload files and videos for use in lessons and pages. Videos transcode after upload — poll the media item until uploadStatus is ready. You can also generate images with AI (synchronous; spends the workspace's AI credits) and start video transcription (spends transcription minutes; returns 202 — poll GET /media/{mediaId}/transcript for the result). All routes require a Authorization: Bearer header — see Authentication.

List media

GET/media

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

folder?string

Response Body

`application/json`

curl -X GET "https://example.com/media"

{  "count": 0,  "media": [    {      "id": "string",      "name": "string",      "type": "string",      "mimeType": "string",      "size": 0,      "url": "string",      "folder": "string",      "uploadStatus": "string",      "createdAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Upload a file

POST/media

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Original file name — sanitized for the stored object + Media Library label.

mimeType*string

MIME type, e.g. image/png.

data*string

Base64-encoded file bytes (no data: prefix).

folder?string

Optional Media Library folder name.

description?string

Optional human description stored on the media doc.

Response Body

`application/json`

curl -X POST "https://example.com/media" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "mimeType": "string",    "data": "string"  }'

{  "mediaId": "string",  "url": "string",  "storagePath": "string"}

{  "error": "string",  "message": "string"}

Start a video upload

POST/media/videos/initiate-upload

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Begin a Bunny video upload: provisions a Bunny video object + a Pending MediaDocument, and returns a signed TUS credential. The caller then uploads the bytes DIRECTLY to Bunny (the file never passes through the API), and polls GET /media/:mediaId until uploadStatus is ready (Bunny finalizes via webhook).

title*string

sourceSizeBytes*number

Source-file byte count — persisted as MediaDocument.size and used for the quota pre-check.

Response Body

`application/json`

curl -X POST "https://example.com/media/videos/initiate-upload" \  -H "Content-Type: application/json" \  -d '{    "title": "string",    "sourceSizeBytes": 0  }'

{  "mediaId": "string",  "bunnyVideoId": "string",  "bunnyLibraryId": "string",  "signature": "string",  "expire": 0}

{  "error": "string",  "message": "string"}

Generate an AI image

POST/media/ai-images

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Generate ONE AI image into the Media Library. Synchronous (up to ~1 min); spends the workspace's AI credits. 402 no-credits, 413 storage-quota-exceeded, 502 image-generation-failed.

prompt*string

The creator's prompt (platform single-graphic guards are appended server-side).

aspectRatio*AIImageAspectRatio

Aspect ratio = the SHAPE of the generated image, independent of resolution. The value is the literal string the provider expects (Gemini's image_config.aspect_ratio), so the UI control is the single source of truth and no pixel mapping is needed.

Curated to the formats a non-technical creator actually publishes — labelled by use-case in the UI (Square / Portrait / Story / Widescreen), not pixels.

Value in

"1:1"
"4:5"
"9:16"
"16:9"

quality*AIImageQuality

Clamped to what the configured model supports.

Value in

"1K"
"2K"
"4K"

folder?string

Media Library folder NAME to file the image under.

textLanguage?string

Language code any text rendered inside the image must use (e.g. pl).

Response Body

`application/json`

curl -X POST "https://example.com/media/ai-images" \  -H "Content-Type: application/json" \  -d '{    "prompt": "string",    "aspectRatio": "1:1",    "quality": "1K"  }'

{  "mediaId": "string",  "url": "string",  "name": "string"}

{  "error": "string",  "message": "string"}

Move media into a folder

POST/media/move

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Files the items into folder (by NAME); folder: null unfiles them.

mediaIds*array<string>

folder*string|null

Response Body

`application/json`

curl -X POST "https://example.com/media/move" \  -H "Content-Type: application/json" \  -d '{    "mediaIds": [      "string"    ],    "folder": "string"  }'

{  "updatedCount": 0}

{  "error": "string",  "message": "string"}

Media detail

GET/media/{mediaId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

mediaId*string

Media id

Response Body

`application/json`

curl -X GET "https://example.com/media/string"

{  "media": {    "id": "string",    "name": "string",    "type": "string",    "mimeType": "string",    "size": 0,    "url": "string",    "folder": "string",    "uploadStatus": "string",    "createdAt": "string"  }}

{  "error": "string",  "message": "string"}

Update media details

PATCH/media/{mediaId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

mediaId*string

Media id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

New display name — must be non-empty.

description?|

New description; null (or blank) clears it; omit to leave untouched.

Response Body

`application/json`

curl -X PATCH "https://example.com/media/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "mediaId": "string",  "updated": true}

{  "error": "string",  "message": "string"}

Delete a media item

DELETE/media/{mediaId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

mediaId*string

Media id

Response Body

`application/json`

curl -X DELETE "https://example.com/media/string"

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Video transcript

GET/media/{mediaId}/transcript

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

`application/json`

curl -X GET "https://example.com/media/string/transcript"

{  "transcription": {    "text": "string",    "language": "string",    "createdAt": "string",    "updatedAt": "string",    "words": [      {        "word": "string",        "start": 0,        "end": 0      }    ]  }}

{  "error": "string",  "message": "string"}

Start video transcription

POST/media/{mediaId}/transcribe

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

mediaId*string

Media id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Start background transcription for a video. Spends transcription minutes (duration-aware). 202 on accept; poll GET /media/:mediaId/transcript.

language?string

Explicit language code; omitted = workspace default → provider auto-detect.

force?boolean

Re-transcribe even when a completed transcript exists (spends minutes again).

Response Body

`application/json`

curl -X POST "https://example.com/media/string/transcribe" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "queued",  "queuedAt": "string"}

{  "error": "string",  "message": "string"}

List folders

GET/media-folders

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/media-folders"

{  "count": 0,  "folders": [    {      "id": "string",      "name": "string"    }  ]}

{  "error": "string",  "message": "string"}

Create a folder

POST/media-folders

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Response Body

`application/json`

curl -X POST "https://example.com/media-folders" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "folder": {    "id": "string",    "name": "string"  }}

{  "error": "string",  "message": "string"}

Rename a media folder

PATCH/media-folders/{name}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

name*string

Folder name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Renaming onto an existing folder MERGES into it (the old folder is removed).

newName*string

Response Body

`application/json`

curl -X PATCH "https://example.com/media-folders/string" \  -H "Content-Type: application/json" \  -d '{    "newName": "string"  }'

{  "folder": {    "id": "string",    "name": "string"  },  "updatedItemCount": 0}

{  "error": "string",  "message": "string"}

Delete a folder

DELETE/media-folders/{name}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

name*string

Folder name

Response Body

`application/json`

curl -X DELETE "https://example.com/media-folders/string"

{  "docDeleted": true,  "unfiledItemCount": 0}

{  "error": "string",  "message": "string"}

Was this article helpful?

Spotted something off? Tell us at support@zanfia.com.

List media

200application/json

4XXapplication/json

Upload a file

200application/json

4XXapplication/json

Start a video upload

200application/json

4XXapplication/json

Generate an AI image

200application/json

4XXapplication/json

Move media into a folder

200application/json

4XXapplication/json

Media detail

200application/json

4XXapplication/json

Update media details

200application/json

4XXapplication/json

Delete a media item

200application/json

4XXapplication/json

Video transcript

200application/json

4XXapplication/json

Start video transcription

200application/json

4XXapplication/json

List folders

200application/json

4XXapplication/json

Create a folder

200application/json

4XXapplication/json

Rename a media folder

200application/json

4XXapplication/json

Delete a folder

200application/json

4XXapplication/json

Related articles

API overview

Authentication and API keys

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`