Export API

Endpoints for image compression and export.

Export Images

Start the export pipeline for images in a session. Returns a Server-Sent Events (SSE) stream with real-time progress.

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",
             "title": "Golden Gate Bridge at Sunset",
             "alt": "Golden Gate Bridge at sunset"
           }
         }
       ],
       "settings": {
         "format": "webp",
         "preset": "high",
         "responsive": false
       }
     }' \
     https://your-api-domain.com/image-forge-api/v1/sessions/sess_abc123def456/export

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

Request Body

FieldTypeRequiredDescription
sessionIdstringYesSession ID from the upload step
imagesarrayYesArray of image objects to export
images[].idstringYesImage ID from the upload response
images[].uploadPathstringYesServer-side file path
images[].originalFilenamestringYesOriginal filename
images[].metadataobjectNoAI metadata (if available). Contains filename for renaming.
settingsobjectYesExport configuration

Settings Object

FieldTypeDefaultDescription
formatstring"webp"Output format: webp, avif, jpeg, png, or original
presetstring"high"Quality preset: maximum, very_high, high, medium, low, minimum
responsivebooleanfalseGenerate responsive size variants
responsiveSizesobject[]—Custom breakpoints when responsive is true

SSE Events

EventDescription
progressFired during processing. Contains imageId, status, step, current, total.
completeFired when all images are exported. Contains full results array with variant details.
errorFired on failure. Contains error message.

Export Result Object

Each image result contains an array of variants:

FieldTypeDescription
namestringVariant name (e.g., full, 1024w, 768w)
pathstringServer-side path to the exported file
sizenumberFile size in bytes
widthnumberImage width in pixels
heightnumberImage height in pixels

Filename Behavior

  • If images[].metadata.filename exists, it's used as the output basename (e.g., golden-gate-bridge-sunset.webp)
  • If no metadata filename, the original filename is used with the new extension (e.g., photo1.webp)

Credit Cost

1 credit per image. Credits are deducted by the Flask API gateway before proxying.

Download Exported File

Download a specific exported file from a session.

curl -H "X-API-Key: sk-your-key-here" \
     "https://your-api-domain.com/image-forge-api/v1/sessions/sess_abc123def456/download?filename=golden-gate-bridge-sunset.webp"

Method: GETPath: /v1/sessions/:sessionId/downloadQuery Parameters: filename — the exported filename to download Response: Binary file with appropriate Content-Type header

Analyze API
Endpoints for AI image analysis.
Sample API
Endpoints for free sample preview exports.