FLflorafauna-ai
Assets

Create an asset upload

Changed on

Creates an asset via one of three paths. (1) Direct bytes: send multipart/form-data with a file part (≤4 MB) plus workspace_id — FLORA stores the bytes and returns a ready asset in one call. (2) Server-side fetch: send JSON with source set to any public HTTPS URL (≤50 MB) — FLORA fetches the bytes with SSRF protection (private/loopback/metadata IPs and redirects to them are blocked) and stores them. (3) Signed upload: send JSON with source="signed-url" to reserve a presigned upload URL for files larger than 4 MB; upload the bytes, then call the complete endpoint. Allowed types: images (jpeg, png, webp, gif, avif, heic, heif), video (mp4, webm, quicktime), audio (mpeg, wav, ogg, mp4/m4a), pdf, and GLB (model/gltf-binary). GLB requires project_id; signed GLB uploads also require exact local file length as size_bytes and use the returned raw-byte PUT descriptor. GLBs are validated before readiness. Images are capped at 150 MP. project_id associates the asset with a project; supported static media are surfaced on its canvas, while GLB Model3D assets are not auto-placed. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

post/assets

Request

  • Base URL
    https://app.flora.ai/api/v1
  • URL
    https://app.flora.ai/api/v1/assets
  • Auth
    HTTP bearer

Request body

sourcestring required

Asset source as a string: either "signed-url" to reserve a direct upload URL, or a public HTTPS URL for server-side fetch.

workspace_idstring required

Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws_.

project_idstring

Project identifier. Use the public API ID returned by list projects; it must start with prj_. Static media uploads may be surfaced on the project's canvas; GLB Model3D assets are associated with the project but are not auto-placed.

folderstring

Destination folder

content_typestring

Asset content type

file_namestring

Asset file name

size_bytesinteger

Exact file size in bytes; required for signed GLB uploads.

Example request

{
  "source": "signed-url",
  "workspace_id": "ws_abc123",
  "project_id": "prj_abc123",
  "folder": "campaign-assets",
  "content_type": "image/png",
  "file_name": "hero.png",
  "size_bytes": 1048576
}

Response

Asset upload created.

asset_idstring required

Asset identifier

uploaded_via'url' | 'signed_url' | 'direct' required

Asset source: "url" (server-side fetch), "signed_url" (presigned upload reservation), or "direct" (multipart bytes streamed in this request).

urlstring uri required

Asset URL

workspace_idstring required

Workspace identifier

visibility'workspace' required
status'pending_upload' | 'ready' | 'failed' required
upload_urlstring

Upload URL (serialized)

expires_atstring date-time

Expiration time for the upload URL

Example response

{
  "asset_id": "asset_abc123",
  "workspace_id": "ws_abc123",
  "upload_url": "https://storage.googleapis.com/flora-user-assets"
}

Changes

  • a8351619f225Revision changes
    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

  • d7653e24b083Revision changes
    • breaking

      the response's property type changed from object to no type for status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • info

      added the new optional request property

    • info

      added subschema #1 subschema #2 to the response property anyOf list for the response status