Space Settings

Space settings allow you to configure default behaviors, security policies, and feature toggles that apply to all media sources within a space. Individual sources can override these defaults.

Default Transformation

Set a default transformation that is automatically applied to all media served from your space. This is useful for enforcing consistent output format, quality, or size across all images.

For example, you can set a default quality of 80 and format of webp so all images are automatically optimized without needing to specify these parameters in every URL.

PATCH /accounts/self/spaces/{spaceId}/media-settings

{
  "defaultTransformation": {
    "output": {
      "format": "WEBP",
      "quality": 80,
      "stripMetadata": true
    }
  }
}

Tip

Default transformations are applied first, then any URL parameters override them. This means you can set sensible defaults while still allowing per-request customization.

Aliased Transformations

Create named presets for commonly used transformation combinations. Instead of repeating the same set of parameters, define an alias and reference it with a single parameter.

Property	Description
aliasedTransformations	Map of alias names to transformation definitions
restrictToKnownAliases	When true, only aliased transformations are allowed

Alias names must be 1-16 characters, lowercase letters, digits, and hyphens only.

Example: Create an alias called thumbnail:

{
  "aliasedTransformations": {
    "thumbnail": {
      "resize": {
        "width": 200,
        "height": 200,
        "mode": "FIT"
      },
      "output": {
        "format": "WEBP",
        "quality": 75
      }
    }
  }
}

Then use it in your URL:

?alias=thumbnail

Restrict to Known Aliases

When restrictToKnownAliases is set to true, only pre-defined aliased transformations are accepted. Any request with custom transformation parameters will be rejected. This is useful for:

• Preventing unexpected image sizes or formats
• Controlling bandwidth usage
• Enforcing brand-consistent image outputs

Watermarks

Manage watermark images that can be applied to your media. Watermarks are uploaded once and referenced by name in transformation URLs.

Upload a Watermark

POST /accounts/self/spaces/{spaceId}/media-settings/watermarks

Upload a watermark image file with a name. Use PNG format for transparency support.

Download a Watermark

GET /accounts/self/spaces/{spaceId}/media-settings/watermarks/{watermarkName}

Delete a Watermark

DELETE /accounts/self/spaces/{spaceId}/media-settings/watermarks/{watermarkName}

Security

Configure how media access is secured in your space.

Transformation Security Level

Level	Description
Token	Requires JWT token authentication for all requests
Signature	Requires URL signature with validity duration
Unsecured	No authentication required (use with caution)

API Keys

Generate scoped API keys for programmatic access to your space.

POST /accounts/self/spaces/{spaceId}/media-settings/api-keys

Each API key has:

• A unique key ID for reference
• Scoped permissions
• The ability to be revoked individually

DELETE /accounts/self/spaces/{spaceId}/media-settings/api-keys/{apiKeyId}

Signature Keys

Generate ECDSA key pairs for URL signature verification.

POST /accounts/self/spaces/{spaceId}/media-settings/signature-keys

Allowed Origins

Configure CORS allowed origins for your media. Supports:

• Exact domain matching (e.g., https://example.com)
• Wildcard subdomains (e.g., https://*.example.com)
• Custom ports (e.g., http://localhost:3000)
• Wildcard * to allow all origins
• Maximum 50 origins per space

Adaptive Media Policy

Automatically adjust image quality and dimensions based on client capabilities using Client Hints.

Property	Description
enabled	Enable or disable adaptive media
maxDpr	Maximum device pixel ratio to support (max: 5.0)
allowedResolutions	List of allowed width/height pairs
lowerQualityBasedOnNetworkSpeed	Reduce quality for slow network connections

Supported Client Hints:

• Sec-CH-DPR - Device pixel ratio
• Sec-CH-Viewport-Width - Viewport width
• Sec-CH-Width - Resource width
• Sec-CH-ECT - Effective connection type
• Sec-CH-Downlink - Downlink speed

Versioning

Enable file versioning to track the history of media files. When versioning is enabled, previous versions of files are retained when they are overwritten.

{
  "versioning": true
}

Default AI Models

Configure which AI model tier is used by default for AI-powered operations.

Operation	Description	Models Available
Remove Background	Automatically remove image backgrounds	BASIC, QUALITY
AI Edit	Prompt-based image editing	BASIC, QUALITY

{
  "defaultAiModels": {
    "REMOVE_BACKGROUND": "BASIC",
    "AI_EDIT": "QUALITY"
  }
}

Note

The QUALITY model produces better results but costs more per operation. AI pricing is calculated based on output image dimensions (megapixels).

Max Source Media Content Length

Set the maximum allowed file size for uploaded media. Default is 25 MB.

{
  "maxSourceMediaContentLength": 26214400
}

Source-Level Overrides

Individual media sources can override space-level settings. This allows you to apply different security policies, default transformations, or watermarks to specific sources.

PATCH /accounts/self/spaces/{spaceId}/sources/{sourceId}/settings

Override any of the following per source:

• Default transformation
• Watermarks
• Security configuration
• Adaptive media policy
• Aliased transformations

Settings not explicitly overridden will inherit from the space defaults.