Sample API

Endpoints for free sample preview exports.

Start Sample Export

Export up to 5 images as a free preview. Uses the same export pipeline but does not deduct credits.

Request

SSE Stream

curl -X POST \
     -H "X-API-Key: sk-your-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "sessionId": "sess_abc123def456",
       "images": [
         {
           "id": "img_001",
           "uploadPath": "/tmp/sessions/sess_abc123def456/photo1.jpg",
           "originalFilename": "photo1.jpg",
           "metadata": { "filename": "golden-gate-bridge-sunset" }
         }
       ],
       "settings": {
         "format": "webp",
         "preset": "high"
       }
     }' \
     https://your-api-domain.com/image-forge-api/v1/sessions/sess_abc123def456/sample

Method: POSTPath: /v1/sessions/:sessionId/sampleAuthentication: Required Response: text/event-stream (SSE)

Limits

Maximum 5 images per sample request
Requests with more than 5 images return a 400 error

Credit Cost

Free — no credits are deducted for sample exports. Samples are intended for preview and comparison only.

Request Body

The request body is identical to the Export API — same images array and settings object.

Session Isolation

Sample exports use a separate session namespace ({sessionId}-sample) to avoid overwriting files from a full export. This means you can sample and export independently without conflict.

Differences from Full Export

Feature	Full Export	Sample Export
Credit cost	1 per image	Free
Image limit	No limit	5 max
Used for WP replacement	Yes	No
Downloadable as ZIP	No	No
Cached for final export	Yes	Yes