API
Media
Keep the workspace's pictures (SVG and raster originals) and videos, with previews and a record of which documents use them.
An asset is an original the workspace keeps in its media library: an SVG the editor rasterised into a page (svg-original), a PNG, JPEG, GIF or WebP it placed (image), or an MP4, QuickTime or WebM video (video). The kind is read from the bytes and the file's structure is checked, so a file cut short, damaged, or not what its name says is refused with a code saying why. An upload of bytes already kept returns the existing asset, and every original counts toward the plan's storage. An SVG must load nothing from outside the file, and is never served where it could run: downloads are attachments, and an SVG's thumbnail, like a video's poster frame, is a raster preview the client sends (assets.setPreview).
Assets are filed in media folders, paths such as /brand/2026/ (assetFolders.*; assets.list takes folder, assets.upload a folder to file in, assets.move refiles). Media folders are their own tree, apart from document folders, and have no access rules: whoever can list the media library sees every folder. A folder is renamed or moved with everything in it, and deleted only when it is empty.
A video is at most 95 MiB, sent with a Content-Length and streamed into storage as it arrives; its width, height and durationMs are read from the file. A video is never placed as a picture: picture pickers list kind=image,svg-original, and assets.recordUsages, a look's pictures, an enrichment gallery and a document's imageLayout refuse one.
After saving a version that contains pictures made from assets, record them with assets.recordUsages. assets.get then lists the documents that use an asset. While any do, or while an enrichment gallery shows it, assets.delete refuses with 409 asset_in_use unless force=true. Documents keep their pictures when an original is deleted. Documents in folders the caller cannot see are counted, never named.
A PNG, JPEG, GIF or WebP picture can be converted to PNG (animated PNG when it moves), JPEG, WebP, AVIF, GIF, TIFF, BMP, ICO, HEIC or JPEG XL, with each format's options and crop, turn, flip and resize applied to every frame (assets.transform, or assetTransforms.download for bytes sent as the body), and the result downloaded or kept as a new asset (assets.transformSave, assetTransforms.save; the library keeps PNG, JPEG, WebP and GIF). assets.animation says whether a picture moves; assets.extractFrames keeps an animation's frames in a new folder. Conversions run in the engine container, within limits each route states, and are limited to 20 a minute per caller and per address.
Store a picture or a video in the media library
POST /assets assets.upload
Send an SVG (at most 10 MiB), a PNG, JPEG, GIF or WebP image (at most 25 MiB), or an MP4, QuickTime (.mov) or WebM video (at most 95 MiB) as the body.
The kind is read from the bytes, never the name, and the file's structure is checked, not just its first bytes: a PNG's chunks from IHDR to IEND, with the checksums of IHDR, PLTE, IDAT and IEND; a JPEG's segments from SOI to the EOI that ends its image (bytes after that EOI, such as a phone's motion-photo video, are kept); a GIF's blocks to its trailer; a WebP's RIFF size against the file.
Bytes after a picture's end (IEND, the trailer, the RIFF size) are kept, as browsers ignore them. Then an MP4's or MOV's top-level boxes tiling the whole file, one moov with a duration and a video track with a picture size, and at least one mdat; a WebM's EBML header (DocType webm), Segment, Info, Tracks with a video track, and Clusters, every element within the file.
An SVG must be UTF-8 with an <svg> root, no DOCTYPE or entity declarations, and nothing that loads from outside the file (images and fonts in it must be data: URLs); it is kept as sent. For a picture, width, height and dpi record what the editor made of it; for a video they are ignored, and its width, height and durationMs are read from the file.
A video is streamed into storage as it arrives, so it must be sent with a Content-Length (411 length_required without one), and it is measured against the plan's storage before it is read. Bytes the workspace already keeps return the stored asset, so sending an upload again is safe: an Idempotency-Key is not needed here and is ignored (the body is streamed, never held for a replay).
Refused with a 402 when it would take the workspace past its plan's storage; nothing stored is ever removed for that. Other refusals: 400 empty_body for an empty body; 400 length_mismatch when the body is not as long as its Content-Length; 415 unsupported_asset for anything but those eight types; 415 malformed_svg for an SVG that fails those checks; 413 too_large past the size for its type.
A file whose structure does not hold is refused with 415 and one of these codes, its message saying what is wrong: truncated (the file ends before its structure does (an upload or export cut short)); trailing_data (bytes after an MP4's, MOV's or WebM's end that are not part of it (a picture's are kept)); malformed_structure (a box, chunk, segment or element whose header cannot be right); bad_checksum (a PNG IHDR, PLTE, IDAT or IEND chunk whose CRC does not match); ftyp_not_first (an MP4 whose ftyp box is not its first); no_header (an MP4 or MOV with no moov box, or a WebM with no Segment or Info); duplicate_header (an MP4 or MOV with more than one moov box); no_media_data (no media data: an MP4 without mdat, a WebM without a Cluster, a picture without image data); no_duration (a video that does not say how long it is); no_video_track (a file with no video track, such as audio only); no_video_size (a video track with no picture size); not_webm (a Matroska file whose DocType is not webm (an .mkv)); index_too_large (an MP4 moov over 16 MB, or WebM Info or Tracks over 1 MB); unsupported_brand (an ISO media file that is a HEIF or AVIF image rather than a video).
- Scopes
documents.edit
Query parameters
| Name | Type | Description |
|---|---|---|
filename | string | The name the library shows it by and the original downloads as. Control and direction characters are removed. Left out, it has none. At most 200 characters. |
width | number | A picture's width as the editor reports it, stored with the asset. Not checked against the bytes. Ignored for a video. More than 0. At most 1,000,000. |
height | number | A picture's height as the editor reports it, stored with the asset. Not checked against the bytes. Ignored for a video. More than 0. At most 1,000,000. |
dpi | number | A picture's resolution in dots per inch as the editor reports it, stored with the asset. Not checked against the bytes. Ignored for a video. More than 0. At most 1,000,000. |
folder | string | The media folder to file it in, made with its ancestors if it does not exist: a path such as /brand/2026/. Left out, /. Bytes the workspace already keeps stay where they are. 1 to 1,100 characters. |
Request body
The raw bytes, at most 95 MiB, sent as application/octet-stream.
Response
201 Created. A JSON object:
Response fields (17)
| Name | Type | Description |
|---|---|---|
asset | object | The stored asset: the new one, or the one the workspace already kept with these bytes. |
asset.id | string | The asset's id. |
asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
asset.size | number | The original's size in bytes. |
asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
deduplicated | boolean | True when the workspace already kept these bytes: the existing asset is returned unchanged, and the query values given are ignored. |
Example request
curl -X POST https://api.flipbird.io/api/v1/assets \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-1.bin Example response
{
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
},
"deduplicated": true
} List the workspace's media library, newest first
GET /assets assets.list
kind keeps one kind, or several separated by commas: image,svg-original lists the pictures, which is what a picture picker shows. q matches part of the filename, or an asset id. Pass next back as cursor for the following page. documents counts the documents using a picture that you may open; hiddenDocuments counts those in folders you cannot see. A video is never used by a document, so both are 0.
folder keeps the assets in that media folder and, unless subfolders=false, in the folders under it, as documents.list does.
- Scopes
documents.read- MCP tool
assets_list
Query parameters
| Name | Type | Description |
|---|---|---|
kind | string | One kind (svg-original, image, video), or several separated by commas. Left out, every kind. Matches ^(?:svg-original|image|video)(?:,(?:svg-original|image|video))*$. |
folder | string | Only this media folder and, unless subfolders is false, those under it. Left out, /: every folder. 1 to 1,100 characters. |
subfolders | string | false lists only the assets filed in folder itself. Left out, true: the folders under it too. One of true, false. |
q | string | Part of a filename to match, without regard to case, or an asset's whole id. At most 200 characters. |
cursor | string | The previous page's next. Left out, the first page. Matches ^\d{1,16}\.ast_[0-9a-z]{20}$. |
limit | integer | Most assets to return. Default 50. 1 to 200. |
Response
200 OK. A JSON object:
Response fields (19)
| Name | Type | Description |
|---|---|---|
assets | array of objects | This page's assets, newest first. Deleted assets are not listed. |
assets[].id | string | The asset's id. |
assets[].kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
assets[].contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
assets[].filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
assets[].size | number | The original's size in bytes. |
assets[].sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
assets[].width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
assets[].height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
assets[].dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
assets[].durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
assets[].folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
assets[].hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
assets[].previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
assets[].createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
assets[].createdAt | number | When it was uploaded, in epoch milliseconds. |
assets[].documents | number | How many documents the caller may open contain a picture made from it. |
assets[].hiddenDocuments | number | How many documents in folders the caller cannot see contain a picture made from it: counted, never named. |
next | string | Pass it back as cursor for the next page. Null when this page holds fewer than limit. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/assets \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"assets": [
{
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000,
"documents": 1,
"hiddenDocuments": 1
}
],
"next": "string"
} One asset, with the documents that contain a picture made from it
GET /assets/{assetId} assets.get
usedIn names only documents you may open; hiddenDocuments counts the others, in folders you cannot see. galleries names the documents you may open whose enrichment galleries show it, and hiddenGalleries counts the others. Documents that have been purged from the trash are not counted. An unknown or deleted asset answers 404 not_found.
- Scopes
documents.read- MCP tool
assets_get
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id. An id starting ast_. |
Response
200 OK. A JSON object:
Response fields (27)
| Name | Type | Description |
|---|---|---|
asset | object | The asset. |
asset.id | string | The asset's id. |
asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
asset.size | number | The original's size in bytes. |
asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
usedIn | array of objects | The documents the caller may open whose recorded versions contain a picture made from it (assets.recordUsages), most recently recorded first. |
usedIn[].documentId | string | The document's id. |
usedIn[].title | string | The document's title. |
usedIn[].trashed | boolean | Whether the document is in the trash. |
usedIn[].versions | array of numbers | The document's version numbers that contain the picture, newest first. |
hiddenDocuments | number | How many other documents, in folders the caller cannot see, contain it: counted, never named. |
galleries | array of objects | The documents the caller may open whose enrichment galleries show it, by title. |
galleries[].documentId | string | The document's id. |
galleries[].title | string | The document's title. |
galleries[].trashed | boolean | Whether the document is in the trash. |
hiddenGalleries | number | How many other documents' galleries show it, in folders the caller cannot see: counted, never named. |
Example request
curl https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
},
"usedIn": [
{
"documentId": "…",
"title": "Spring catalogue",
"trashed": true,
"versions": [
1
]
}
],
"hiddenDocuments": 1,
"galleries": [
{
"documentId": "…",
"title": "Spring catalogue",
"trashed": true
}
],
"hiddenGalleries": 1
} Download an asset's original
GET /assets/{assetId}/file assets.download
The original's bytes as stored, with its media type. Always an attachment, named by its filename with its type's extension, with a sandboxing Content-Security-Policy, so an SVG never runs on this site. A video is streamed as it is decrypted, so damage found in storage part way through ends the response early rather than answering 410.
An unknown or deleted asset answers 404 not_found; 410 gone when its file can no longer be read.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id. An id starting ast_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/file \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Store a rasterised preview of an asset
PUT /assets/{assetId}/preview assets.setPreview
A PNG, JPEG or WebP of at most 1 MiB, for the library's thumbnails, replacing any earlier one. The editor sends the raster it already made, so an SVG is never drawn on this site to show it; for a video, the library sends a poster frame it drew. Counts toward the plan's storage: refused with a 402 when it would take the workspace past it.
Other refusals: 415 unsupported_preview when the body is not a PNG, JPEG or WebP; 409 preview_changed when another preview was stored at the same moment; 404 not_found for an unknown or deleted asset. Returns the asset with its new previewSize.
- Scopes
documents.edit.any- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id. An id starting ast_. |
Request body
The raw bytes, at most 1 MiB, sent as application/octet-stream.
Response
200 OK. A JSON object:
Response fields (16)
| Name | Type | Description |
|---|---|---|
asset | object | The asset, with its new preview. |
asset.id | string | The asset's id. |
asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
asset.size | number | The original's size in bytes. |
asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
Example request
curl -X PUT https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/preview \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-1.bin Example response
{
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
}
} An asset's rasterised preview
GET /assets/{assetId}/preview assets.preview
The stored preview, or a raster image itself, served inline with its media type. An SVG or a video with no preview has none (404 no_preview); neither is ever served as its own preview. 410 gone when the file can no longer be read; 404 not_found for an unknown or deleted asset.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id. An id starting ast_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/preview \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Rename an asset
PATCH /assets/{assetId} assets.update
Changes the name the library shows it by and the original downloads as. The bytes, their kind and where they are used stay as they are. A name that is empty once control and direction characters are removed answers 400 invalid_filename. An unknown or deleted asset answers 404 not_found.
- Scopes
documents.edit.any- Retries
- Safe with an
Idempotency-Key - MCP tool
assets_update
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id. An id starting ast_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
filename required | string | The new name. Control and direction characters are removed. 1 to 200 characters. |
Response
200 OK. A JSON object:
Response fields (16)
| Name | Type | Description |
|---|---|---|
asset | object | The asset as renamed. |
asset.id | string | The asset's id. |
asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
asset.size | number | The original's size in bytes. |
asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
Example request
curl -X PATCH https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"filename": "catalogue.pdf"
}' Example response
{
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
}
} Delete an asset
DELETE /assets/{assetId} assets.delete
Refused (409 asset_in_use, naming in error.details.documents the documents you may open and counting the rest as hiddenDocuments) while a document that is not purged contains a picture made from it, or while a document's enrichment gallery shows it (galleries and hiddenGalleries, likewise), unless force=true.
Documents keep their pictures either way: what goes is the original, and its preview; a gallery that showed it shows its other images, and a look that used it shows nothing in its place. The record of which documents used it stays. An unknown or already deleted asset answers 404 not_found.
- Scopes
documents.edit.any- Retries
- Safe with an
Idempotency-Key - MCP tool
assets_delete
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id. An id starting ast_. |
Query parameters
| Name | Type | Description |
|---|---|---|
force | string | true deletes it even while documents contain pictures made from it or galleries show it. Left out, false. One of true, false. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Record which pictures from the library a saved version contains
POST /documents/{documentId}/versions/{version}/assets assets.recordUsages
Call it after saving a version, with the asset ids the editor placed in it. It needs edit access to the document. Every id must be a live asset of this workspace (422 unknown_assets, listing those that are not in error.details.missing, and nothing is recorded), and a picture: a video is never placed in a document (422 not_pictures, listing the videos in error.details.videos, and nothing is recorded).
Recording one twice is harmless. A version the document does not have answers 404 not_found; 403 forbidden when the caller may only view the document.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
version required | integer | The version's number. At least 1. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
assetIds required | array of strings | The ids of the pictures (SVG originals and images) the version contains. An id given twice counts once. 1 to 200 items. |
Response
200 OK. A JSON object:
Response fields (2)
| Name | Type | Description |
|---|---|---|
recorded | number | How many were new: an asset already recorded for this version is not counted again. |
assetIds | array of strings | The asset ids recorded for the version, each once. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/assets \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [
"ast_7m2kq9vx4c8d1r5t6wnb"
]
}' Example response
{
"recorded": 1,
"assetIds": [
"string"
]
} The pictures from the library a version is recorded as containing
GET /documents/{documentId}/versions/{version}/assets assets.versionUsages
What assets.recordUsages recorded for this version, oldest first, each with whether the original has since been deleted (a deleted one cannot be recorded again). The editor reads it when it saves the next version, to record the pictures that version still holds. It needs access to open the document: one in a folder you cannot see is a 404, as is a document of another workspace.
A version the document does not have answers 404 not_found.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
version required | integer | The version's number. At least 1. |
Response
200 OK. A JSON object:
Response fields (4)
| Name | Type | Description |
|---|---|---|
version | number | The version's number. |
assets | array of objects | The assets recorded for the version, oldest record first. |
assets[].id | string | The asset's id. |
assets[].deleted | boolean | Whether the asset has been deleted since it was recorded. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/assets \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"version": 1,
"assets": [
{
"id": "string",
"deleted": true
}
]
} List the media library's folders
GET /asset-folders assetFolders.list
Every media folder, sorted: /, each folder made with assetFolders.create or by filing an asset in it (empty ones included), and the folders above each. Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.
- Scopes
documents.read- MCP tool
asset_folders_list
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
folders | array of strings | Media folder paths, sorted, / first. |
Example request
curl https://api.flipbird.io/api/v1/asset-folders \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"folders": [
"string"
]
} Create a media folder, including its ancestors
POST /asset-folders assetFolders.create
Makes the folder and any folder above it that does not exist yet, and returns the path as stored. A folder that exists already is left as it is (created false). A path that is not a valid folder answers 400 invalid. Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
asset_folders_create
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
path required | string | The folder's path: a path such as /brand/2026/. 1 to 1,100 characters. |
Response
201 Created. A JSON object:
Response fields (2)
| Name | Type | Description |
|---|---|---|
path | string | The folder's path as stored, ending in /. |
created | boolean | Whether it was made now; false when it existed already. |
Example request
curl -X POST https://api.flipbird.io/api/v1/asset-folders \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"path": "string"
}' Example response
{
"path": "string",
"created": true
} Rename or move a media folder
POST /asset-folders/move assetFolders.move
Moves the folder from to the path to: the folder, every folder under it and every asset in or under it take the new path together, and the folders above to are made. Folders are not merged: a to that exists already (a folder, or an asset filed there or under it) answers 409 folder_exists.
Moving /, moving a folder into itself or a folder under it, or a move that would put a folder under it more than 12 levels deep answers 400 invalid_folder_move; a from with nothing in it and no folder answers 404 not_found; a path that is not a valid folder answers 400 invalid.
Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
asset_folders_move
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
from required | string | The folder to move: a path such as /brand/2026/. 1 to 1,100 characters. |
to required | string | Its new path. To rename /brand/old/, give /brand/new/; to move it, give a path under another folder. 1 to 1,100 characters. |
Response
200 OK. A JSON object:
Response fields (4)
| Name | Type | Description |
|---|---|---|
from | string | The folder's old path, as stored. |
to | string | Its new path, as stored. |
folders | number | How many folders moved: the folder and those under it that were kept as folders. |
assets | number | How many assets moved with it. |
Example request
curl -X POST https://api.flipbird.io/api/v1/asset-folders/move \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"from": "string",
"to": "string"
}' Example response
{
"from": "string",
"to": "string",
"folders": 1,
"assets": 1
} Delete an empty media folder
DELETE /asset-folders assetFolders.delete
Deletes the folder and the folders under it, only while no asset is filed in it or under it: 409 folder_not_empty otherwise, with error.details.assets counting them. Move or delete those first. / cannot be deleted (400 invalid); a folder that does not exist answers 404 not_found.
Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
asset_folders_delete
Query parameters
| Name | Type | Description |
|---|---|---|
path required | string | The folder to delete: a path such as /brand/2026/. 1 to 1,100 characters. |
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
folders | number | How many folders were deleted: the folder and the empty ones under it. |
Example request
curl -X DELETE "https://api.flipbird.io/api/v1/asset-folders?path=string" \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Example response
{
"folders": 1
} File assets in a media folder
POST /asset-folders/assets assets.move
Moves each of these assets to the folder, made with its ancestors if it does not exist. Every id must be a live asset of this workspace (422 unknown_assets, listing those that are not in error.details.missing, and nothing moves); a path that is not a valid folder answers 400 invalid.
Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
assets_move
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
assetIds required | array of strings | The assets to move. An id given twice counts once. 1 to 200 items. |
folder required | string | The folder to file them in: a path such as /brand/2026/. 1 to 1,100 characters. |
Response
200 OK. A JSON object:
Response fields (2)
| Name | Type | Description |
|---|---|---|
folder | string | The folder as stored. |
moved | number | How many assets were filed there. |
Example request
curl -X POST https://api.flipbird.io/api/v1/asset-folders/assets \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [
"ast_7m2kq9vx4c8d1r5t6wnb"
],
"folder": "/catalogues"
}' Example response
{
"folder": "/catalogues",
"moved": 1
} Convert a picture in the library and download the result
POST /assets/{assetId}/transform assets.transform
Converts the asset's original to any of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl, with its options, and the geometry the editor applied (ops) replayed on every frame, so an animation stays one where the format can hold it.
The converted file is the response: its media type, an attachment named after the source with the format's extension, a sandboxing Content-Security-Policy, and X-Image-Width, X-Image-Height, X-Image-Frames and X-Image-Adjusted (true when a faster setting than the one asked was used to fit the time) headers. Nothing is stored.
It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.
Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).
A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits. An SVG or a video answers 422 unsupported_image; an unknown or deleted asset 404 not_found.
- Scopes
documents.edit
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
transform required | object | The conversion: output says what to write; geometry, background, animation and metadata choices apply to every format. |
transform.output required | object | The format to write, one of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl, and that format's own options. One of 10 shapes, chosen by format. |
transform.output.format required | string | png: PNG. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl. |
transform.output.options | object | PNG's options. Each left out takes its default. Only when format is png. Default {}. |
transform.output.options.compression | string | Compression: How hard to work at making the file smaller. The pixels are the same either way. One of fast, balanced, smallest; left out, balanced. One of fast, balanced, smallest. Default balanced. |
transform.output.options | object | JPEG's options. Each left out takes its default. Only when format is jpeg. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 85. 1 to 100. Default 85. |
transform.output.options.progressive | boolean | Progressive: Shows a rough picture first while it loads. Left out, true. Default true. |
transform.output.options.chroma | string | Chroma subsampling: How much colour detail to keep. 4:4:4 keeps it all, for text and sharp edges; 4:2:0 is smallest. One of 4:2:0, 4:2:2, 4:4:4; left out, 4:2:0. One of 4:2:0, 4:2:2, 4:4:4. Default 4:2:0. |
transform.output.options | object | WebP's options. Each left out takes its default. Only when format is webp. Default {}. |
transform.output.options.lossless | boolean | Lossless: Keeps every pixel exactly. Quality then sets how hard it works at a small file. Left out, false. Default false. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 80. 0 to 100. Default 80. |
transform.output.options.effort | integer | Effort: 0 is fastest, 6 makes the smallest file. 0 to 6; left out, 4. 0 to 6. Default 4. |
transform.output.options | object | AVIF's options. Each left out takes its default. Only when format is avif. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 60. 0 to 100. Default 60. |
transform.output.options.speed | integer | Speed: 6 makes the smallest file, 10 is fastest. 6 to 10; left out, 6. 6 to 10. Default 6. |
transform.output.options.lossless | boolean | Lossless: Keeps every pixel exactly; the file is much larger. Left out, false. Default false. |
transform.output.options | object | GIF's options. Each left out takes its default. Only when format is gif. Default {}. |
transform.output.options.colours | integer | Colours: Fewer colours make a smaller file. 2 to 256; left out, 256. 2 to 256. Default 256. |
transform.output.options.dither | string | Dithering: How the missing colours are mixed from those kept. One of floyd-steinberg, riemersma, none; left out, floyd-steinberg. One of floyd-steinberg, riemersma, none. Default floyd-steinberg. |
transform.output.options.optimise | boolean | Optimise: Stores only what changes between frames. Left out, true. Default true. |
transform.output.options.lossy | integer | Lossy compression: 0 is off. Higher trades some noise for a smaller file. 0 to 200; left out, 0. 0 to 200. Default 0. |
transform.output.options | object | TIFF's options. Each left out takes its default. Only when format is tiff. Default {}. |
transform.output.options.compression | string | Compression: LZW and ZIP are lossless; JPEG is lossy and drops transparency. One of none, lzw, zip, jpeg; left out, lzw. One of none, lzw, zip, jpeg. Default lzw. |
transform.output.options | object | BMP's options. Each left out takes its default. Only when format is bmp. Default {}. |
transform.output.options | object | ICO (icon)'s options. Each left out takes its default. Only when format is ico. Default {}. |
transform.output.options.sizes | array of numbers | Sizes: The square sizes, in pixels, the icon holds. Any of 16, 24, 32, 48, 64, 128, 256; left out, 16, 32, 48. 1 to 7 items. Default [16,32,48]. |
transform.output.options | object | HEIC's options. Each left out takes its default. Only when format is heic. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 50. 1 to 100. Default 50. |
transform.output.options | object | JPEG XL's options. Each left out takes its default. Only when format is jxl. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail; 100 is lossless. 1 to 100; left out, 90. 1 to 100. Default 90. |
transform.output.options.effort | integer | Effort: 1 is fastest, 7 makes the smallest file. 1 to 7; left out, 7. 1 to 7. Default 7. |
transform.output.options.lossless | boolean | Lossless: Keeps every pixel exactly (the same as quality 100). Left out, false. Default false. |
transform.ops | array of objects | Geometry applied in order to every frame, at most 16: what the image editor did to a picture, replayed on the original so an animation keeps its frames. Coordinates are in the picture as it stands after the operations before. Left out, none. At most 16 items. Default []. |
transform.ops[].op required | string | crop: keep a rectangle of the picture as it stands after the operations before this one. One of crop, rotate, flip, resize. |
transform.ops[].x required | integer | The rectangle's left edge, in pixels from the top left. Only when op is crop. 0 to 15,999. |
transform.ops[].y required | integer | The rectangle's top edge, in pixels from the top left. Only when op is crop. 0 to 15,999. |
transform.ops[].width required | integer | The rectangle's width, in pixels. Only when op is crop. 1 to 16,000. |
transform.ops[].height required | integer | The rectangle's height, in pixels. Only when op is crop. 1 to 16,000. |
transform.ops[].degrees required | number | 90, 180 or 270, clockwise. Only when op is rotate. One of 90, 180, 270. |
transform.ops[].direction required | string | horizontal mirrors left to right; vertical turns it upside down without turning it. Only when op is flip. One of horizontal, vertical. |
transform.ops[].width | integer | The box's width in pixels. Left out, it follows from height and the picture's shape. Only when op is resize. 1 to 16,000. |
transform.ops[].height | integer | The box's height in pixels. Left out, it follows from width and the picture's shape. Only when op is resize. 1 to 16,000. |
transform.ops[].fit | string | contain fits the picture inside the box, keeping its shape; cover fills the box, keeping its shape and cutting what spills over from the centre (needs width and height); stretch makes it exactly the box (needs width and height). Left out, contain. Only when op is resize. One of contain, cover, stretch. Default contain. |
transform.ops[].upscale | boolean | Whether a picture smaller than the box is made larger. Left out, false: it keeps its size (cover then cuts it to the box). Only when op is resize. Default false. |
transform.animation | string | For an animated source: keep keeps every frame where the format can hold them, first keeps the first frame only. Left out, keep. One of keep, first. Default keep. |
transform.loop | integer | How many times an animation plays, 0 for ever. Left out, as the source says. AVIF ignores it and always loops for ever. 0 to 65,535. |
transform.stripMetadata | boolean | Removes EXIF, XMP, comments and the colour profile. Left out, true. A JPEG is turned upright by its EXIF orientation first either way. Kept only in a still PNG, JPEG, WebP, GIF, TIFF or HEIC; an animated PNG or WebP, AVIF and JPEG XL never keep them. Default true. |
transform.background | string | The colour, as #rrggbb, a picture is laid on for a format without transparency (JPEG, BMP, TIFF with JPEG compression). Left out, white. Matches ^#[0-9a-fA-F]{6}$. Default #ffffff. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl -X POST https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/transform \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transform": {
"output": {
"format": "png"
}
}
}' \
-OJ Convert a picture in the library and keep the result as a new asset
POST /assets/{assetId}/transform/save assets.transformSave
The conversion of assets.transform, kept. Kept as a new asset in the media library, which keeps PNG, JPEG, WebP, GIF (the other formats are only downloaded: 422 not_kept). The result is checked as an upload is (its structure, from its bytes) and counts toward the plan's storage: refused with a 402 when it would take the workspace past it, checked before the converter runs and again as the asset is recorded.
Bytes the workspace already keeps return the stored asset. The original is never replaced. A repeat with the same Idempotency-Key returns the first answer. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.
Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).
A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
transform required | object | The conversion: output says what to write; geometry, background, animation and metadata choices apply to every format. |
transform.output required | object | The format to write, one of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl, and that format's own options. One of 10 shapes, chosen by format. |
transform.output.format required | string | png: PNG. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl. |
transform.output.options | object | PNG's options. Each left out takes its default. Only when format is png. Default {}. |
transform.output.options.compression | string | Compression: How hard to work at making the file smaller. The pixels are the same either way. One of fast, balanced, smallest; left out, balanced. One of fast, balanced, smallest. Default balanced. |
transform.output.options | object | JPEG's options. Each left out takes its default. Only when format is jpeg. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 85. 1 to 100. Default 85. |
transform.output.options.progressive | boolean | Progressive: Shows a rough picture first while it loads. Left out, true. Default true. |
transform.output.options.chroma | string | Chroma subsampling: How much colour detail to keep. 4:4:4 keeps it all, for text and sharp edges; 4:2:0 is smallest. One of 4:2:0, 4:2:2, 4:4:4; left out, 4:2:0. One of 4:2:0, 4:2:2, 4:4:4. Default 4:2:0. |
transform.output.options | object | WebP's options. Each left out takes its default. Only when format is webp. Default {}. |
transform.output.options.lossless | boolean | Lossless: Keeps every pixel exactly. Quality then sets how hard it works at a small file. Left out, false. Default false. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 80. 0 to 100. Default 80. |
transform.output.options.effort | integer | Effort: 0 is fastest, 6 makes the smallest file. 0 to 6; left out, 4. 0 to 6. Default 4. |
transform.output.options | object | AVIF's options. Each left out takes its default. Only when format is avif. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 60. 0 to 100. Default 60. |
transform.output.options.speed | integer | Speed: 6 makes the smallest file, 10 is fastest. 6 to 10; left out, 6. 6 to 10. Default 6. |
transform.output.options.lossless | boolean | Lossless: Keeps every pixel exactly; the file is much larger. Left out, false. Default false. |
transform.output.options | object | GIF's options. Each left out takes its default. Only when format is gif. Default {}. |
transform.output.options.colours | integer | Colours: Fewer colours make a smaller file. 2 to 256; left out, 256. 2 to 256. Default 256. |
transform.output.options.dither | string | Dithering: How the missing colours are mixed from those kept. One of floyd-steinberg, riemersma, none; left out, floyd-steinberg. One of floyd-steinberg, riemersma, none. Default floyd-steinberg. |
transform.output.options.optimise | boolean | Optimise: Stores only what changes between frames. Left out, true. Default true. |
transform.output.options.lossy | integer | Lossy compression: 0 is off. Higher trades some noise for a smaller file. 0 to 200; left out, 0. 0 to 200. Default 0. |
transform.output.options | object | TIFF's options. Each left out takes its default. Only when format is tiff. Default {}. |
transform.output.options.compression | string | Compression: LZW and ZIP are lossless; JPEG is lossy and drops transparency. One of none, lzw, zip, jpeg; left out, lzw. One of none, lzw, zip, jpeg. Default lzw. |
transform.output.options | object | BMP's options. Each left out takes its default. Only when format is bmp. Default {}. |
transform.output.options | object | ICO (icon)'s options. Each left out takes its default. Only when format is ico. Default {}. |
transform.output.options.sizes | array of numbers | Sizes: The square sizes, in pixels, the icon holds. Any of 16, 24, 32, 48, 64, 128, 256; left out, 16, 32, 48. 1 to 7 items. Default [16,32,48]. |
transform.output.options | object | HEIC's options. Each left out takes its default. Only when format is heic. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 50. 1 to 100. Default 50. |
transform.output.options | object | JPEG XL's options. Each left out takes its default. Only when format is jxl. Default {}. |
transform.output.options.quality | integer | Quality: Higher keeps more detail; 100 is lossless. 1 to 100; left out, 90. 1 to 100. Default 90. |
transform.output.options.effort | integer | Effort: 1 is fastest, 7 makes the smallest file. 1 to 7; left out, 7. 1 to 7. Default 7. |
transform.output.options.lossless | boolean | Lossless: Keeps every pixel exactly (the same as quality 100). Left out, false. Default false. |
transform.ops | array of objects | Geometry applied in order to every frame, at most 16: what the image editor did to a picture, replayed on the original so an animation keeps its frames. Coordinates are in the picture as it stands after the operations before. Left out, none. At most 16 items. Default []. |
transform.ops[].op required | string | crop: keep a rectangle of the picture as it stands after the operations before this one. One of crop, rotate, flip, resize. |
transform.ops[].x required | integer | The rectangle's left edge, in pixels from the top left. Only when op is crop. 0 to 15,999. |
transform.ops[].y required | integer | The rectangle's top edge, in pixels from the top left. Only when op is crop. 0 to 15,999. |
transform.ops[].width required | integer | The rectangle's width, in pixels. Only when op is crop. 1 to 16,000. |
transform.ops[].height required | integer | The rectangle's height, in pixels. Only when op is crop. 1 to 16,000. |
transform.ops[].degrees required | number | 90, 180 or 270, clockwise. Only when op is rotate. One of 90, 180, 270. |
transform.ops[].direction required | string | horizontal mirrors left to right; vertical turns it upside down without turning it. Only when op is flip. One of horizontal, vertical. |
transform.ops[].width | integer | The box's width in pixels. Left out, it follows from height and the picture's shape. Only when op is resize. 1 to 16,000. |
transform.ops[].height | integer | The box's height in pixels. Left out, it follows from width and the picture's shape. Only when op is resize. 1 to 16,000. |
transform.ops[].fit | string | contain fits the picture inside the box, keeping its shape; cover fills the box, keeping its shape and cutting what spills over from the centre (needs width and height); stretch makes it exactly the box (needs width and height). Left out, contain. Only when op is resize. One of contain, cover, stretch. Default contain. |
transform.ops[].upscale | boolean | Whether a picture smaller than the box is made larger. Left out, false: it keeps its size (cover then cuts it to the box). Only when op is resize. Default false. |
transform.animation | string | For an animated source: keep keeps every frame where the format can hold them, first keeps the first frame only. Left out, keep. One of keep, first. Default keep. |
transform.loop | integer | How many times an animation plays, 0 for ever. Left out, as the source says. AVIF ignores it and always loops for ever. 0 to 65,535. |
transform.stripMetadata | boolean | Removes EXIF, XMP, comments and the colour profile. Left out, true. A JPEG is turned upright by its EXIF orientation first either way. Kept only in a still PNG, JPEG, WebP, GIF, TIFF or HEIC; an animated PNG or WebP, AVIF and JPEG XL never keep them. Default true. |
transform.background | string | The colour, as #rrggbb, a picture is laid on for a format without transparency (JPEG, BMP, TIFF with JPEG compression). Left out, white. Matches ^#[0-9a-fA-F]{6}$. Default #ffffff. |
filename | string | The new asset's name. Control and direction characters are removed. Left out, the source's name with the format's extension. At most 200 characters. |
folder | string | The media folder to file it in, made with its ancestors if it does not exist: a path such as /brand/2026/. Left out, the source's folder. 1 to 1,100 characters. |
Response
201 Created. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
asset | object | The asset the result is kept as: a new one, or the one the workspace already kept with these bytes. |
asset.id | string | The asset's id. |
asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
asset.size | number | The original's size in bytes. |
asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
deduplicated | boolean | True when the workspace already kept these exact bytes: that asset is returned, where it is filed, and nothing new is stored. |
result | object | What the conversion made. |
result.format | string | The format written. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl. |
result.contentType | string | Its media type. |
result.extension | string | Its file extension, without the dot. |
result.width | number | The result's width in pixels (an icon's largest size). |
result.height | number | The result's height in pixels. |
result.frames | number | Frames in the result: 1 unless an animation was kept. |
result.animated | boolean | Whether the result is an animation. |
result.loop | number | How many times the animation plays, 0 for ever; null for a still. Can be null. |
result.sourceFrames | number | Frames in the source. |
result.size | number | The result's size in bytes. |
result.settings | map of anys | The format's options the result was written with: those asked for, defaults filled, or a faster setting when those would not have fitted the time. |
result.adjusted | boolean | True when settings differ from what was asked: a conversion that would take too long at the setting asked is written at the slowest faster setting that fits (a higher AVIF speed, a lower WebP or JPEG XL effort) rather than refused. |
Example request
curl -X POST https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/transform/save \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"transform": {
"output": {
"format": "png"
}
}
}' Example response
{
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
},
"deduplicated": true,
"result": {
"format": "png",
"contentType": "string",
"extension": "string",
"width": 1,
"height": 1,
"frames": 1,
"animated": true,
"loop": 1,
"sourceFrames": 1,
"size": 1,
"settings": {},
"adjusted": true
}
} Convert a picture sent as the body and download the result
POST /asset-transforms assetTransforms.download
For the image editor's flattened canvas: send a PNG, JPEG, GIF or WebP of at most 25 MiB as application/octet-stream, and the conversion as the transform query value.
The converted file is the response: its media type, an attachment named after the source with the format's extension, a sandboxing Content-Security-Policy, and X-Image-Width, X-Image-Height, X-Image-Frames and X-Image-Adjusted (true when a faster setting than the one asked was used to fit the time) headers. Nothing is stored.
To keep an animation under the editor's crop, turn, flip and resize, convert the asset itself (assets.transform) with those as ops. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.
Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).
A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.
- Scopes
documents.edit
Query parameters
| Name | Type | Description |
|---|---|---|
transform required | string | The conversion as JSON, the same object as the body of assets.transform's transform (URL-encoded): {"output":{"format":"webp","options":{"quality":80}}}. 400 invalid_request when it is not valid JSON or not a valid conversion. 2 to 8,192 characters. |
filename | string | The name the download is given, its extension replaced by the format's. Left out, image. At most 200 characters. |
Request body
The raw bytes, at most 25 MiB, sent as application/octet-stream.
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl -X POST "https://api.flipbird.io/api/v1/asset-transforms?transform=string" \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-1.bin \
-OJ Convert a picture sent as the body and keep the result as a new asset
POST /asset-transforms/save assetTransforms.save
The conversion of assetTransforms.download, kept. Kept as a new asset in the media library, which keeps PNG, JPEG, WebP, GIF (the other formats are only downloaded: 422 not_kept). The result is checked as an upload is (its structure, from its bytes) and counts toward the plan's storage: refused with a 402 when it would take the workspace past it, checked before the converter runs and again as the asset is recorded.
Bytes the workspace already keeps return the stored asset. The original is never replaced. A repeat with the same Idempotency-Key returns the first answer. The picture sent is not kept, only the result. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.
Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).
A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Query parameters
| Name | Type | Description |
|---|---|---|
transform required | string | The conversion as JSON, the same object as the body of assets.transform's transform (URL-encoded): {"output":{"format":"webp","options":{"quality":80}}}. 400 invalid_request when it is not valid JSON or not a valid conversion. 2 to 8,192 characters. |
filename | string | The new asset's name. Control and direction characters are removed. Left out, image with the format's extension. At most 200 characters. |
folder | string | The media folder to file it in, made with its ancestors if it does not exist: a path such as /brand/2026/. Left out, /. 1 to 1,100 characters. |
Request body
The raw bytes, at most 25 MiB, sent as application/octet-stream.
Response
201 Created. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
asset | object | The asset the result is kept as: a new one, or the one the workspace already kept with these bytes. |
asset.id | string | The asset's id. |
asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
asset.size | number | The original's size in bytes. |
asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
deduplicated | boolean | True when the workspace already kept these exact bytes: that asset is returned, where it is filed, and nothing new is stored. |
result | object | What the conversion made. |
result.format | string | The format written. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl. |
result.contentType | string | Its media type. |
result.extension | string | Its file extension, without the dot. |
result.width | number | The result's width in pixels (an icon's largest size). |
result.height | number | The result's height in pixels. |
result.frames | number | Frames in the result: 1 unless an animation was kept. |
result.animated | boolean | Whether the result is an animation. |
result.loop | number | How many times the animation plays, 0 for ever; null for a still. Can be null. |
result.sourceFrames | number | Frames in the source. |
result.size | number | The result's size in bytes. |
result.settings | map of anys | The format's options the result was written with: those asked for, defaults filled, or a faster setting when those would not have fitted the time. |
result.adjusted | boolean | True when settings differ from what was asked: a conversion that would take too long at the setting asked is written at the slowest faster setting that fits (a higher AVIF speed, a lower WebP or JPEG XL effort) rather than refused. |
Example request
curl -X POST "https://api.flipbird.io/api/v1/asset-transforms/save?transform=string" \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-1.bin Example response
{
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
},
"deduplicated": true,
"result": {
"format": "png",
"contentType": "string",
"extension": "string",
"width": 1,
"height": 1,
"frames": 1,
"animated": true,
"loop": 1,
"sourceFrames": 1,
"size": 1,
"settings": {},
"adjusted": true
}
} Keep an animation's frames as pictures in a new media folder
POST /assets/{assetId}/frames assets.extractFrames
Takes frames out of an animated GIF, WebP or PNG, each drawn whole (as the animation shows it, not just the part that changed), with ops applied to each, as PNG, JPEG or WebP, at most 100 frames and 24 MiB together (422 too_many_frames or too_large otherwise). They are kept in a new folder inside folder, named after the picture (name (2) and so on when that name is taken), each named after its frame.
A frame whose bytes the workspace already keeps is that asset, where it is filed.
Each frame is checked as an upload is and counts toward the plan's storage: the frames together are checked against it before the first is stored (402 otherwise); should storage fill between that check and the last frame (another upload at the same moment), the frames stored by then stay and the answer is a 402 whose error.details gives folder and stored.
The folder is made with the first frame not already kept, so when every frame is (a repeat), none is made and folder is null. A still answers with its one frame. A repeat with the same Idempotency-Key returns the first answer. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.
Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).
A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
frames | object | Which frames to take and how to write them: at most 100 frames, together at most 24 MiB. Default {}. |
frames.format | string | Each frame's format: png, jpeg or webp (lossy). Left out, png. One of png, jpeg, webp. Default png. |
frames.quality | integer | For jpeg and webp: 1 to 100. Left out, 85 for JPEG and 80 for WebP. Ignored for png. 1 to 100. |
frames.start | integer | The first frame to take, counted from 0. Left out, 0. 0 to 999. Default 0. |
frames.end | integer | The last frame to take, counted from 0 and included. Left out, the animation's last frame. Past the last, the last. 0 to 999. |
frames.every | integer | Take every nth frame from start: 1 takes them all, 2 every other. Left out, 1. 1 to 1,000. Default 1. |
frames.ops | array of objects | Geometry applied in order to every frame, at most 16: what the image editor did to a picture, replayed on the original so an animation keeps its frames. Coordinates are in the picture as it stands after the operations before. Left out, none. At most 16 items. Default []. |
frames.ops[].op required | string | crop: keep a rectangle of the picture as it stands after the operations before this one. One of crop, rotate, flip, resize. |
frames.ops[].x required | integer | The rectangle's left edge, in pixels from the top left. Only when op is crop. 0 to 15,999. |
frames.ops[].y required | integer | The rectangle's top edge, in pixels from the top left. Only when op is crop. 0 to 15,999. |
frames.ops[].width required | integer | The rectangle's width, in pixels. Only when op is crop. 1 to 16,000. |
frames.ops[].height required | integer | The rectangle's height, in pixels. Only when op is crop. 1 to 16,000. |
frames.ops[].degrees required | number | 90, 180 or 270, clockwise. Only when op is rotate. One of 90, 180, 270. |
frames.ops[].direction required | string | horizontal mirrors left to right; vertical turns it upside down without turning it. Only when op is flip. One of horizontal, vertical. |
frames.ops[].width | integer | The box's width in pixels. Left out, it follows from height and the picture's shape. Only when op is resize. 1 to 16,000. |
frames.ops[].height | integer | The box's height in pixels. Left out, it follows from width and the picture's shape. Only when op is resize. 1 to 16,000. |
frames.ops[].fit | string | contain fits the picture inside the box, keeping its shape; cover fills the box, keeping its shape and cutting what spills over from the centre (needs width and height); stretch makes it exactly the box (needs width and height). Left out, contain. Only when op is resize. One of contain, cover, stretch. Default contain. |
frames.ops[].upscale | boolean | Whether a picture smaller than the box is made larger. Left out, false: it keeps its size (cover then cuts it to the box). Only when op is resize. Default false. |
frames.background | string | The colour, as #rrggbb, a picture is laid on for a format without transparency (JPEG, BMP, TIFF with JPEG compression). Left out, white. Matches ^#[0-9a-fA-F]{6}$. Default #ffffff. |
folder | string | The folder to make the new folder in: a path such as /brand/2026/. Left out, the picture's own folder. 1 to 1,100 characters. |
name | string | The new folder's name, without slashes. Left out, the picture's name without its extension, or Frames when it has none. At most 70 characters. |
Response
201 Created. A JSON object:
Response fields (25)
| Name | Type | Description |
|---|---|---|
folder | string | The new folder's path, as stored; null when every frame was already kept, in which case no folder is made. Can be null. |
format | string | The frames' format. One of png, jpeg, webp. |
width | number | Each frame's width in pixels. |
height | number | Each frame's height in pixels. |
sourceFrames | number | Frames in the animation. |
frames | array of objects | The frames taken, in order. |
frames[].index | number | The frame's place in the animation, counted from 0. |
frames[].delayMs | number | How long the animation shows it, in milliseconds. |
frames[].asset | object | The asset the frame is kept as. |
frames[].asset.id | string | The asset's id. |
frames[].asset.kind | string | svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video. |
frames[].asset.contentType | string | The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm. |
frames[].asset.filename | string | The name the library shows it by and the original downloads as. Empty when none was given. |
frames[].asset.size | number | The original's size in bytes. |
frames[].asset.sha256 | string | The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content. |
frames[].asset.width | number | A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null. |
frames[].asset.height | number | A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null. |
frames[].asset.dpi | number | A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null. |
frames[].asset.durationMs | number | A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null. |
frames[].asset.folder | string | The media folder it is filed in: a path such as /brand/2026/, or / for the top level. |
frames[].asset.hasPreview | boolean | Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview). |
frames[].asset.previewSize | number | The stored preview's size in bytes, or null when there is none. Can be null. |
frames[].asset.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
frames[].asset.createdAt | number | When it was uploaded, in epoch milliseconds. |
frames[].deduplicated | boolean | True when the workspace already kept these bytes, so the existing asset is returned where it is filed. |
Example request
curl -X POST https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/frames \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"frames": {},
"folder": "/catalogues"
}' Example response
{
"folder": "/catalogues",
"format": "png",
"width": 1,
"height": 1,
"sourceFrames": 1,
"frames": [
{
"index": 1,
"delayMs": 1,
"asset": {
"id": "string",
"kind": "svg-original",
"contentType": "string",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"width": 1,
"height": 1,
"dpi": 1,
"durationMs": 1,
"folder": "/catalogues",
"hasPreview": true,
"previewSize": 1,
"createdBy": "string",
"createdAt": 1767225600000
},
"deduplicated": true
}
]
} Whether a picture is animated, and how
GET /assets/{assetId}/animation assets.animation
Read from the picture's bytes without decoding it, for an editor deciding whether to offer to keep an animation or take its frames out. convertible says whether it is within the conversion limits, and refusal why not. An SVG or a video answers 422 unsupported_image; an unknown or deleted asset 404 not_found; 410 gone when its file can no longer be read.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
assetId required | string | The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_. |
Response
200 OK. A JSON object:
Response fields (9)
| Name | Type | Description |
|---|---|---|
contentType | string | The picture's media type, read from its bytes. |
width | number | Its width as shown, in pixels (a JPEG's EXIF orientation applied). |
height | number | Its height as shown, in pixels. |
animated | boolean | Whether it has more than one frame. |
frames | number | Its frames: 1 for a still. |
loop | number | How many times it plays, 0 for ever; null for a still. Can be null. |
durationMs | number | How long one play lasts, in milliseconds, as the file says; null for a still. Can be null. |
convertible | boolean | Whether it is within the limits a conversion or a frame extraction takes. |
refusal | string | Why it is not, as the conversion would say; null when it is. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/animation \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"contentType": "string",
"width": 1,
"height": 1,
"animated": true,
"frames": 1,
"loop": 1,
"durationMs": 1,
"convertible": true,
"refusal": "string"
} Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | empty_body | The upload has no bytes. |
| 400 | length_mismatch | A video's body is not as long as its Content-Length. |
| 400 | invalid_filename | The name is empty once cleaned. |
| 400 | invalid | A media folder path that is not one, or deleting /. |
| 400 | invalid_folder_move | Moving /, moving a media folder into itself or a folder under it, or past 12 levels deep. |
| 404 | no_preview | An SVG or a video with no stored preview. |
| 409 | asset_in_use | Documents or galleries still use the asset. details lists them; send force=true to delete it anyway. |
| 409 | preview_changed | Another preview was stored at the same moment. |
| 409 | folder_exists | Moving a media folder to a path that exists already: folders are not merged. |
| 409 | folder_not_empty | Deleting a media folder with assets in or under it. details.assets counts them. |
| 410 | gone | The stored file can no longer be read. |
| 411 | length_required | A video sent without a Content-Length. |
| 413 | too_large | Past the size for its type: an SVG 10 MiB, an image 25 MiB, a video 95 MiB. |
| 415 | unsupported_asset | The bytes are not SVG, PNG, JPEG, GIF, WebP, MP4, QuickTime or WebM. |
| 415 | malformed_svg | The SVG fails its safety checks. |
| 415 | truncated | The upload's structure does not hold: the file ends before its structure does (an upload or export cut short). |
| 415 | trailing_data | The upload's structure does not hold: bytes after an MP4's, MOV's or WebM's end that are not part of it (a picture's are kept). |
| 415 | malformed_structure | The upload's structure does not hold: a box, chunk, segment or element whose header cannot be right. |
| 415 | bad_checksum | The upload's structure does not hold: a PNG IHDR, PLTE, IDAT or IEND chunk whose CRC does not match. |
| 415 | ftyp_not_first | The upload's structure does not hold: an MP4 whose ftyp box is not its first. |
| 415 | no_header | The upload's structure does not hold: an MP4 or MOV with no moov box, or a WebM with no Segment or Info. |
| 415 | duplicate_header | The upload's structure does not hold: an MP4 or MOV with more than one moov box. |
| 415 | no_media_data | The upload's structure does not hold: no media data: an MP4 without mdat, a WebM without a Cluster, a picture without image data. |
| 415 | no_duration | The upload's structure does not hold: a video that does not say how long it is. |
| 415 | no_video_track | The upload's structure does not hold: a file with no video track, such as audio only. |
| 415 | no_video_size | The upload's structure does not hold: a video track with no picture size. |
| 415 | not_webm | The upload's structure does not hold: a Matroska file whose DocType is not webm (an .mkv). |
| 415 | index_too_large | The upload's structure does not hold: an MP4 moov over 16 MB, or WebM Info or Tracks over 1 MB. |
| 415 | unsupported_brand | The upload's structure does not hold: an ISO media file that is a HEIF or AVIF image rather than a video. |
| 415 | unsupported_preview | The preview is not a PNG, JPEG or WebP. |
| 422 | unknown_assets | Some of the ids are not live assets. details.missing lists them. |
| 422 | not_pictures | Some of the ids are videos, which a version cannot contain. details.videos lists them. |