Skip to main content

​
Overview

Whilter.AI’s Batch Media API enables clients to process and deliver large-scale personalized campaigns using a structured batch-based integration flow. Whether you’re generating thousands of personalized images or videos, this API ensures smooth and efficient execution.

​
High-Level Integration Flow

The batch execution flow consists of the following 5 simple steps:

​
Step 1: Prepare Your Campaign Data

Prepare a CSV file containing:
  • A unique identifier (e.g., customer ID or phone number)
  • Required personalization fields for media generation
Once the CSV is ready, compress it into a ZIP file using the following naming format: WHILTERTEMPLATEID_CLIENTNAME_CAMPAIGNNAME_TIMESTAMP.zip

​
Step 2: Upload the File to SFTP

Upload the ZIP file to the designated input location (e.g., sftp/in) shared during onboarding.

​
Step 3: Trigger the Task via API

Notify Whilter.AI that the file has been uploaded using the Task API.

​
POST /client/task

POST https://<whilter-api-host>/<client>/task

​
Request Headers:

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

​
Request Body:

{
  "client-id": "9e4d1a7c-82b3-4f6a-b1d9-3c8e5a2f7d64",
  "campaign-id": "ClientName_CampaignName",
  "template-id": "c7a9f3b2-5d4e-4c8a-9f12-8b6e4a3d92f1",
  "file-name": "WHILTERTEMPLATEID_CLIENTNAME_CAMPAIGNNAME_TIMESTAMP.zip",
  "file-path": "sftp.client/campiagn/in/WHILTERTEMPLATEID_CLIENTNAME_CAMPAIGNNAME_TIMESTAMP.zip",
  "row-count": 1000000,
  "expected-output-duration": 1
}

​
Sample Response:

{
  "message": "Task created successfully.",
  "client-id": "9e4d1a7c-82b3-4f6a-b1d9-3c8e5a2f7d64",
  "campaign-id": "ClientName_CampaignName",
  "template-id": "c7a9f3b2-5d4e-4c8a-9f12-8b6e4a3d92f1",
  "task-id": "f2c8a9e4-6b31-4d7a-9f0e-1c5a8b7d3e62",
}

​
Step 4: Check Task Status (Optional)

Track task progress using the task ID.

​
GET /client/task/status/<task-id>

GET https://<whilter-api-host>/<client>/task/status/<task-id>

​
Request Headers:

{
  "Authorization": "Bearer <access-token>"
}

​
Sample Response:

{
    "message": "Task is in progress.",
  "task-id": "f2c8a9e4-6b31-4d7a-9f0e-1c5a8b7d3e62",
  "status": "pending | in-progress | completed",
  "count": 0,
  "file-path": "sftp.client/campiagn/in/WHILTERTEMPLATEID_CLIENTNAME_CAMPAIGNNAME_TIMESTAMP.zip"
}
The output file will mirror your input CSV but with two additional columns:
  • media-url: Link to the generated media
  • error: If generation failed for a row

​
Step 5: Cancel a Task (Optional)

This step is optional. If you need to cancel a previously triggered task (for example, due to incorrect data or a campaign change), use the following API.

​
POST /image/task/cancel/{taskId}

POST https://<whilter-api-host>/image/task/cancel/{taskId}

​
Path Parameter:

NameTypeDescription
taskIdstringThe unique identifier of the task to cancel

​
Request Headers:

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

​
Sample Response:

{
  "message": "Task cancelled successfully",
  "client-id": "9e4d1a7c-82b3-4f6a-b1d9-3c8e5a2f7d64",
  "campaign-id": "ClientName_CampaignName",
  "template-id": "c7a9f3b2-5d4e-4c8a-9f12-8b6e4a3d92f1",
  "task-id": "f2c8a9e4-6b31-4d7a-9f0e-1c5a8b7d3e62"
}

​
Callback Support

Instead of polling the status API, you can provide a callback URL, and Whilter.AI will notify your system automatically when the task is completed.

​
Security

All APIs are secured using Bearer Token Authentication. Ensure your access token is kept confidential.
Need help integrating? Contact us or explore more API references in the sidebar.