Testing in Sandbox Mode

SmallPict includes a Logical Sandbox Environment designed for local development, CI/CD automated test pipelines, and staging environments.

Sandbox mode allows you to execute image optimization requests with zero monthly quota deduction and zero risk of affecting production assets.

🧪 Obtaining Sandbox Credentials

1. Go to your SmallPict Dashboard → API Keys.
2. Click Create Sandbox Key.
3. Your key will be generated with the sp_test_... prefix (e.g. sp_test_9a8b7c6d5e4f...).
4. Save your paired secret key securely.

⚙️ Sandbox Architectural Guardrails

When an API call is made with an sp_test_... key:

flowchart LR
    Client[Test Suite / Local App] -->|X-API-Key: sp_test_...| API[SmallPict API]
    API -->|1. Detect Sandbox Prefix| Check{IsSandbox?}
    Check -->|Yes| Quota[Bypass Monthly Quota]
    Check -->|Yes| S3[(Ephemeral S3: 24h Auto-Expiry)]
    API -->|Inject Response Header| Res[X-SmallPict-Sandbox: true]

1. Zero Quota Deduction: The QuotaService skips deduction, so your development testing never consumes paid production credits.
2. Ephemeral S3 Storage (24-Hour TTL): Converted test images are stored in a designated sandbox prefix (sandbox/{customer_id}/{job_id}/) and automatically deleted after 24 hours.
3. Response Header Identification: Every response from sandbox requests includes the HTTP header X-SmallPict-Sandbox: true.
4. Single-File Limit: Sandbox mode permits testing files up to 25MB.

💻 Example SDK Usage in Sandbox

Node.js

import { SmallPict } from '@smallpict/sdk';
import fs from 'node:fs';

const sandboxClient = new SmallPict({
  apiKey: 'sp_test_1234567890abcdef...',
  secretKey: 'sec_test_secret123...'
});

const result = await sandboxClient.optimize(fs.readFileSync('sample.jpg'), {
  format: 'avif',
  quality: 80
});

console.log('Sandbox conversion succeeded:', result.url);

cURL

curl -X POST https://api.smallpict.app/v1/optimize \
  -H "X-API-Key: sp_test_1234567890abcdef..." \
  -H "X-Timestamp: 1716301234" \
  -H "X-Signature: 3a9f8b2c4d6e..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "sample.jpg",
    "mime_type": "image/jpeg",
    "filesize": 500000,
    "options": { "format": "webp", "quality": 80 }
  }'