Workspace files

The dashboard's workspace Files page is an archive for generated images and videos. Generated outputs appear there automatically and expire after 30 days. It does not provide a manual upload workflow. The API also supports uploading reference inputs for generation requests; those files are accessible through the Files API but are not shown in the generated-output browser. The file bytes are stored under data/files by default; set CAPI_FILES_DIR to a persistent volume path when deploying.

Upload an API reference input

The API accepts multipart uploads up to 25 MiB. Supported formats are PNG, JPEG, WebP, GIF, MP4, WebM, MP3, MP4 audio, WAV, and PDF.

curl -X POST "$CAPI_BASE_URL/v1/files" \
  -H "Authorization: Bearer $CAPI_API_KEY" \
  -F "file=@./portrait.png" \
  -F "purpose=vision"

The response contains a workspace-scoped file_... ID and a short-lived signed url (one hour):

{
  "id": "file_0123456789abcdef0123456789abcdef0123",
  "object": "file",
  "bytes": 482913,
  "filename": "portrait.png",
  "purpose": "vision",
  "content_type": "image/png",
  "url": "https://capi.example/api/v1/files/file_.../content?token=..."
}

The signed URL is a bearer link. Keep it private and request a new one from GET /v1/files/{file_id} when it expires. File operations require the files.write API-key scope. Uploaded reference inputs expire after 30 days.

Use an uploaded image

Responses accepts CAPI file IDs in the normal image input shape. CAPI verifies the file belongs to the key's workspace and sends the image contents to the selected provider:

{
  "model": "your-responses-model",
  "input": [{
    "role": "user",
    "content": [
      { "type": "input_text", "text": "Describe this image." },
      { "type": "input_image", "file_id": "file_0123456789abcdef0123456789abcdef0123" }
    ]
  }]
}

Responses image_generation can also use an input_image reference as a guide. For /v1/images/edits, send image_url as an HTTPS URL, a CAPI file ID, or an array of those values. The multipart form accepts one or more image file fields and an optional mask file. Image URL references must be publicly routable HTTPS URLs on the default port, return a supported image type, and stay within the 25 MiB combined request limit.

curl -X POST "$CAPI_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $CAPI_API_KEY" \
  -F "model=your-image-model" \
  -F "prompt=Replace the background with a snowy street" \
  -F "image=@./portrait.png"

For video providers, pass the returned signed url in the provider's reference-image/video URL field. Signed URLs expire after one hour; submit the video task before they expire.

Generated output archive

Successful image generations and completed video tasks are copied into the workspace file library. Image responses keep the upstream result fields and add capi_file_id, capi_url, and archive_status to each result. Video task results return a fresh signed download URL and file_id after each status request. Archived outputs expire and are removed automatically after 30 days; a workspace manager can also delete them earlier from the Files page or through the Files API. Video outputs up to 512 MiB are archived; if an upstream result cannot be fetched or exceeds that limit, the task still returns the provider URL when available.

List, inspect, and delete

curl "$CAPI_BASE_URL/v1/files?limit=50" \
  -H "Authorization: Bearer $CAPI_API_KEY"

curl "$CAPI_BASE_URL/v1/files/file_0123456789abcdef0123456789abcdef0123" \
  -H "Authorization: Bearer $CAPI_API_KEY"

curl -X DELETE "$CAPI_BASE_URL/v1/files/file_0123456789abcdef0123456789abcdef0123" \
  -H "Authorization: Bearer $CAPI_API_KEY"

GET /v1/files/{file_id} returns a fresh signed content URL. The API list includes uploaded reference inputs and generated outputs; it supports limit (1–100) and a creation-time cursor. Deleting a file removes both its metadata and stored bytes. Expired files are cleaned hourly. Workspace members can browse and preview generated outputs in the dashboard; only workspace owners and admins can delete them there.

Storage and backups

The SQLite database stores file metadata and signed-token hashes; file contents live in the configured files directory. Back up both together. In multi-instance deployments, all instances must share the same persistent file directory and database.