pi-ds-files

DeepSeek Files API for Pi. Upload an image once, reference it by file_id in every later request to deepseek-v4-flash-vision-exp — instead of re-sending base64 every time.

• Reuses the same image across requests (content-hash cache, no duplicate uploads)
• Bypasses the 32 MiB inline image limit (Files API accepts up to 64 MiB)
• Works automatically with the deepseek provider in pi
• Zero runtime dependencies (Node built-ins only)

Install

pi install npm:pi-ds-files

Requires pi ≥ 0.6 and the DeepSeek API key already configured for the deepseek provider (in ~/.pi/agent/models.json or ~/.pi/agent/auth.json, or DEEPSEEK_API_KEY).

Add the vision model if you do not have it yet:

pi --list-models | grep vision-exp

How it works

image in provider payload (base64)
        │
        ▼
pi.on("before_provider_request")
        │
        ▼
hash(mime + bytes) ──► cache hit ──► reuse file_id
        │
        └────────────► cache miss ──► POST https://api.deepseek.com/files
                                     (multipart, purpose=user_data)
        │
        ▼
image block ──► { "type": "file", "file_id": "file-api-…" }

Only requests whose provider matches providerPatterns (default deepseek) and model matches modelPatterns (default deepseek-v4-flash-vision-exp) are rewritten. Everything else passes through untouched. If an upload fails, the original inline image is kept — a request is never broken.

Commands

| Command | What it does | | --- | --- | | /ds-files status | Show config, cache size, active model | | /ds-files list [--limit N] [--order asc\|desc] | List uploaded files | | /ds-files upload <path> [--expires SECONDS] | Upload an image, cache the file_id | | /ds-files delete <file_id> | Delete a remote file | | /ds-files prune | Drop expired/overflow cache entries | | /ds-files on / /ds-files off | Enable/disable rewriting | | /ds-files cache <path> | Point the cache at a custom file |

CLI

The package also installs a ds-files binary for scripting:

ds-files upload screenshot.png
ds-files upload big.png --expires 86400
ds-files list --limit 50
ds-files delete file-api-xxxxxxxxxxxxxxxx
ds-files status

Configuration

Config lives at ~/.pi/agent/extensions/pi-ds-files.json:

{
  "enabled": true,
  "providerPatterns": ["deepseek"],
  "modelPatterns": ["deepseek-v4-flash-vision-exp"],
  "maxCacheEntries": 500,
  "defaultExpirySeconds": null,
  "autoUpload": true,
  "verbose": false
}

• defaultExpirySeconds: null = permanent, or 3600–2592000 (1h–30d)
• autoUpload: when false, cache hits still rewrite but new images stay inline
• Cache file: ~/.pi/agent/pi-ds-files-cache.json (override with cachePath or PI_DS_FILES_CACHE)

Limits (DeepSeek Files API)

• Formats: JPEG, PNG, GIF, WebP
• Max upload: 64 MiB per file
• Storage: 25 GiB per user, 10,000 files
• Expiry: 1h–30d or permanent

Development

npm test
pi -e ./extensions/index.ts   # quick load test

License

MIT