Skip to content

Storage Endpoints

Image storage operations on the Compute Server. All paths are automatically prefixed with compute/ when using R2 storage.

Overview

Method Endpoint Description
GET /storage/images List stored images
GET /storage/images/{path:path} Get image (302 redirect to CDN for R2)
POST /storage/images/{path:path} Save image to storage
DELETE /storage/images/{path:path} Delete image from storage
HEAD /storage/images/{path:path} Check if image exists

Details

List Images

GET /storage/images?prefix=generations/&limit=100

Returns a list of stored image paths matching the optional prefix filter.

Get Image

GET /storage/images/{path}
  • R2 backend: Returns a 302 redirect to the CDN URL
  • Disk backend: Returns the image content directly via the API

Save Image

POST /storage/images/{path}
Content-Type: multipart/form-data

file: [binary data]

Saves the uploaded file to storage. Returns the stored path and public URL.

Delete Image

DELETE /storage/images/{path}

Removes the image from storage.

Check Existence

HEAD /storage/images/{path}

Returns 200 if the image exists, 404 otherwise.

Storage Backend

The Compute Server selects its storage backend at startup:

Condition Backend Notes
R2_ENDPOINT_URL and R2_ACCESS_KEY_ID configured R2ImageStorage All keys prefixed with compute/
Otherwise DiskImageStorage Local filesystem, public URLs via API endpoint

Path validation prevents directory traversal attacks — absolute paths and .. segments are rejected.

Note: The Backend ingests compute results into its MediaResource system via MediaResourceService.ingest_from_storage_key(relocate=True), copying files from compute/ to canonical media/{resource_id}/file.{ext} paths and marking the source for deferred deletion.

API Reference

Custom API - Storage 1.0.0

This is a very custom OpenAPI schema

Storage

GET /api/v1/storage/images

List Images

Description

List stored images.

Input parameters

Parameter In Type Default Nullable Description
HTTPBearer header string N/A No JWT Bearer token
limit query integer 100 No
prefix query string No

Responses

[
    "string"
]
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "array",
    "items": {
        "type": "string"
    },
    "title": "Response List Images Api V1 Storage Images Get"
}


{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /api/v1/storage/images/{path}

Get Image

Description

Get image by path. Redirects to CDN when using R2 storage.

Input parameters

Parameter In Type Default Nullable Description
HTTPBearer header string N/A No JWT Bearer token
path path string No

Responses

Schema of the response body 



{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /api/v1/storage/images/{path}

Save Image

Description

Save image to storage.

Input parameters

Parameter In Type Default Nullable Description
HTTPBearer header string N/A No JWT Bearer token
path path string No

Request body

{
    "file": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "properties": {
        "file": {
            "type": "string",
            "format": "binary",
            "title": "File"
        }
    },
    "type": "object",
    "required": [
        "file"
    ],
    "title": "Body_save_image_api_v1_storage_images__path__post"
}

Responses

Schema of the response body 



{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

DELETE /api/v1/storage/images/{path}

Delete Image

Description

Delete image from storage.

Input parameters

Parameter In Type Default Nullable Description
HTTPBearer header string N/A No JWT Bearer token
path path string No

Responses

Schema of the response body 



{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

HEAD /api/v1/storage/images/{path}

Check Image Exists

Description

Check if image exists.

Input parameters

Parameter In Type Default Nullable Description
HTTPBearer header string N/A No JWT Bearer token
path path string No

Responses

Schema of the response body 



{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Schemas

Body_save_image_api_v1_storage_images__path__post

Name Type Description
file string(binary)

HTTPValidationError

Name Type Description
detail Array<ValidationError>

ValidationError

Name Type Description
loc Array<>
msg string
type string

Security schemes

Name Type Scheme Description
HTTPBearer http bearer