ImageBundle

ImageBundle is a server-side platform for sports and news photographers to automate photo distribution. You upload images once via FTP, and the system automatically reads the embedded IPTC/XMP metadata, evaluates your routing rules, rewrites metadata where needed, and delivers images to multiple FTP destinations — all without manual intervention.

Typical use cases:

• Route images of Athlete A to their agency FTP, while images of Athlete B go to a different one — simultaneously
• Strip a credit line from descriptions before sending to Shutterstock
• Send all images from an event to 5 general outlets, plus one athlete-specific outlet per image
• Manage multiple independent client workflows (Bundles) from a single server

Every image upload goes through this pipeline:

1. Upload: You drop a JPEG into the bundle_<id> folder via FTP.
2. Bundle Detection: The FTP handler reads the folder name and matches it to a Bundle in the database.
3. Metadata Read: The IPTC engine extracts embedded IPTC-IIM fields and XMP fields (including "Persons Shown" written by Photo Mechanic).
4. Rules Evaluated: The rules engine checks metadata against the bundle's routing rules to determine which destinations should receive the image.
5. IPTC Rewrite: Per-destination transforms are applied (e.g., strip copyright text from caption for Shutterstock).
6. Delivery: The image (with rewritten metadata) is uploaded to each matched destination FTP server via a background Celery worker.

All configuration is done via the REST API. The easiest way is through the Swagger UI at /docs.

A Bundle is the top-level container for a workflow. Create one per client, event type, or distribution channel.

Creating a Bundle

Use POST /api/bundles with:

{
  "name": "Orange Pictures — General",
  "description": "Main distribution bundle for all events"
}

The response includes the bundle's id. Note it down — you'll need it for the upload folder name.

Upload Folder

After creating a bundle with id 3, create a subfolder named bundle_3 in your FTP home directory. Any JPEG you upload there will be processed by Bundle 3's rules.

Bundle Rules

Rules are stored as JSON inside the bundle. Set them via PUT /api/bundles/{id} with a rules field. See the Rules Engine section for the full schema.

A Destination is an FTP server that images are delivered to. Each destination belongs to a Bundle.

Creating a Destination

Use POST /api/destinations:

{
  "bundle_id": 1,
  "name": "Getty Images FTP",
  "destination_type": "ftp",
  "host": "ftp.gettyimages.com",
  "port": 21,
  "username": "your-username",
  "password": "your-password",
  "remote_path": "/uploads"
}

The response includes the destination's id — you'll reference this in your rules.

Testing a Destination

Use POST /api/destinations/{id}/test to verify connectivity before going live. The server will attempt an FTP connection and report success or failure.

ImageBundle runs its own FTP server. Connect with your FTP credentials and upload images into the correct bundle subfolder.

Connection Details

Folder Structure

After connecting, you will land in your home directory. Create subfolders named after your bundle IDs:

# Your FTP home directory
/
├── bundle_1/     # → processed by Bundle 1
├── bundle_2/     # → processed by Bundle 2
└── bundle_6/     # → processed by Bundle 6 (test)

Upload JPEG files into the appropriate folder. Processing starts automatically within a few seconds. Only JPEG files are processed; other formats are ignored.

What Happens Next

After upload, a background job is created. You can monitor it via GET /api/jobs. Each job shows the processing status and a list of distributions (one per matched destination) with their delivery status.

Rules are stored as a JSON object on the Bundle. They tell ImageBundle what to do with each uploaded image. Rules are set via PUT /api/bundles/{id} with a rules field.

The top-level structure:

{
  "version": 1,
  "rules": [ /* array of rule objects */ ],
  "destination_transforms": { /* optional, per-destination rewrites */ }
}

distribute_all

Send every image to one or more destinations, unconditionally.

{
  "type": "distribute_all",
  "destination_ids": [1, 2, 3]
}

filtered_distribute

Send images only when metadata matches a condition. Supports multiple filters, each with their own destination list.

{
  "type": "filtered_distribute",
  "filters": [
    {
      "field": "persons_shown",
      "operator": "contains",
      "value": "Femke Kok",
      "destination_ids": [4]
    }
  ]
}

Full example: athlete routing

{
  "version": 1,
  "rules": [
    {
      "type": "distribute_all",
      "destination_ids": [1, 2, 3, 4, 5]  // always send to all 5
    },
    {
      "type": "filtered_distribute",
      "filters": [
        {
          "field": "persons_shown",
          "operator": "contains",
          "value": "Athlete One",
          "destination_ids": [6]   // also send to Athlete One's agency
        },
        {
          "field": "persons_shown",
          "operator": "contains",
          "value": "Athlete Two",
          "destination_ids": [7]   // also send to Athlete Two's agency
        }
      ]
    }
  ]
}

These are the field names to use in rule filters. They are read from the JPEG's embedded IPTC-IIM data and XMP block.

Transforms let you rewrite metadata before an image is delivered to a specific destination. They are defined in the destination_transforms key at the top level of the bundle's rules JSON.

{
  "version": 1,
  "rules": [ /* ... */ ],
  "destination_transforms": {
    "8": [   // destination id 8 (e.g. Shutterstock)
      {
        "field": "caption",
        "operation": "regex_replace",
        "pattern": "\\s*\\(Photo by [^)]+\\)",
        "replacement": ""
      }
    ]
  }
}

Available transform operations:

ImageBundle supports fully flexible multi-destination routing. A single image can be sent to any combination of destinations simultaneously, with different metadata rewrites per destination.

Scenarios

Split routing example

Send Athlete A only to FTP Y, and Athlete B only to FTP Z (completely separate):

{
  "version": 1,
  "rules": [
    {
      "type": "filtered_distribute",
      "filters": [
        {
          "field": "persons_shown",
          "operator": "contains",
          "value": "Athlete A",
          "destination_ids": [10]
        },
        {
          "field": "persons_shown",
          "operator": "contains",
          "value": "Athlete B",
          "destination_ids": [11]
        }
      ]
    }
  ]
}

FTP credentials are managed per user account. Each user gets a dedicated FTP username and password, independent of their API login.

To view or update credentials, use the Users API:

• GET /api/users — list all users
• PUT /api/users/{id} — update a user's FTP password

Full interactive documentation is at /docs. Quick reference:

Authentication

Bundles

Destinations

Jobs

Users