Dilnaka Python SDK

Install the published Dilnaka Python SDK from PyPI. The package is available online now, so the old editable test install flow is no longer part of the docs.

Package: pypi.org/project/dilnaka

pip install dilnaka

The SDK only needs your API key in .env. It is built specifically for Dilnaka Storage.

DILNAKA_API_KEY=dlk_dev_your_api_key_here

DILNAKA_TIMEOUT=60

Optional: set DILNAKA_TIMEOUT if you want a custom request timeout.

Core flow

Basic upload

Instantiate the client with environment defaults and upload a file with a single method call.

from dilnaka import Dilnaka

client = Dilnaka()

uploaded = client.upload("./test-upload.txt")

print(uploaded.id)
print(uploaded.key)
print(uploaded.status)

Alternate setup

Explicit API key

Pass values directly only when you want to avoid environment variables.

from dilnaka import Dilnaka

client = Dilnaka(
    api_key="dlk_dev_your_api_key_here",
)

uploaded = client.upload("./avatar.png", folder="avatars")
print(uploaded)

Quota model

Storage and Bandwidth Limits

Backend contract

Expected backend endpoints

The SDK expects your Caspian backend to expose the following endpoints.

POST /v1/uploads/presign
POST /v1/uploads/complete
GET  /v1/files
GET  /v1/files/{file_id}
GET  /v1/files/{file_id}/access-url?expiresIn=1200
DELETE /v1/files/{file_id}

Use the access-url endpoint when you need a temporary read URL for one file. Pass expiresIn in seconds to request a shorter or longer lifetime. When omitted, Dilnaka uses the app default signed URL TTL.

API payloads

Presign and complete response shapes

{
  "fileId": "clx_file_id",
  "fileKey": "uploads/2026/05/clx_file_id-test.txt",
  "uploadUrl": "https://s3-presigned-url",
  "expiresIn": 300,
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  }
}

{
  "fileId": "clx_file_id",
  "status": "uploaded",
  "key": "uploads/2026/05/clx_file_id-test.txt",
  "originalName": "test.txt",
  "contentType": "text/plain",
  "size": 94,
  "publicUrl": null
}

{
  "fileId": "clx_file_id",
  "url": "https://s3-presigned-url",
  "expiresIn": 1200,
  "isTemporary": true
}

{
  "success": false,
  "error": "bandwidth_limit_exceeded",
  "message": "Monthly bandwidth limit exceeded. Upgrade your plan or wait until the next billing cycle."
}

{
  "success": true,
  "warning": "bandwidth_overage_active",
  "message": "This account has exceeded included bandwidth. Extra usage will be billed."
}

{
  "success": false,
  "error": "bandwidth_hard_cap_reached",
  "message": "Monthly bandwidth hard cap reached. Contact Dilnaka support to continue serving files."
}

Examples

Common usage patterns

from dilnaka import Dilnaka

client = Dilnaka()

        access = client.get_file_access_url(
          "maext0cfjsquw2mu9o597fb9",
          expires_in=1200,
        )

        print(access.url)
        print(access.expires_in)

from dilnaka import Dilnaka

client = Dilnaka()

file_id = "maext0cfjsquw2mu9o597fb9"
result = client.delete_file(file_id)

print(result)

from dilnaka import Dilnaka

client = Dilnaka()

uploaded = client.upload("./test-upload.txt", folder="uploads")

print("Uploaded file:")
print(f"  id: {uploaded.id}")
print(f"  key: {uploaded.key}")
print(f"  status: {uploaded.status}")
print(f"  size: {uploaded.size}")
print(f"  content_type: {uploaded.content_type}")

from dilnaka import Dilnaka

client = Dilnaka()

for file in client.list_files():
    print(f"{file.id} | {file.status} | {file.key}")

Pricing example

Bandwidth overage example

Pro plan example: you get 100 GB of storage and 50 GB/month of included bandwidth. If your app serves 70 GB in one month, the extra 20 GB is billed as bandwidth overage and service keeps running. Dilnaka only blocks delivery if the plan later reaches its 500 GB monthly safety cap.