> ## Documentation Index
> Fetch the complete documentation index at: https://developer.whilter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Media Generation

> Overview and integration guide for Whilter.AI's Batch Media API

# 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

```mermaid theme={"system"}

sequenceDiagram
    participant Client 
    participant SFTP as Client SFTP Server
    participant S3 as Client S3 Bucket    
    participant Media as Whilter Media Pipeline

    %% Campaign preparation
    Client->>Client: Prepare campaign CSV<br>with personalization fields<br>for Media (Image/Video)
    Client->>Client: Zip and name file

    %% Upload CSV
    Client->>SFTP: Upload zipped<br>campaign CSV file in sftp/in

    Client->>Media: Initiate task via <br> Task-API with <br> relevant Template ID
    Media-->>Client: Return task-id in Response
    

    Media->>SFTP: Fetch zipped CSV file
    SFTP-->>Media: Download zipped file

    %% Processing
    Media->>Media: Unzip, Validate CSV &<br> generate media per row

    Media->>S3: Store generated media
    S3-->>Media: Return Media URLs

    Media->>Media: Write Media URLs <br> into Output CSV

    %% Upload output
    Media->>SFTP: Upload Output CSV <br> to sftp/out

    %% Notification
    Media-->>Client: Task completion callback (Optional)

```

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`

```http theme={"system"}
POST https://<whilter-api-host>/<client>/task
```

#### Request Headers:

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

#### Request Body:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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>`

```http theme={"system"}
GET https://<whilter-api-host>/<client>/task/status/<task-id>
```

#### Request Headers:

```json theme={"system"}
{
  "Authorization": "Bearer <access-token>"
}
```

#### Sample Response:

```json theme={"system"}
{
    "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}`

```http theme={"system"}
POST https://<whilter-api-host>/image/task/cancel/{taskId}
```

#### Path Parameter:

| Name   | Type   | Description                                 |
| ------ | ------ | ------------------------------------------- |
| taskId | string | The unique identifier of the task to cancel |

#### Request Headers:

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

#### Sample Response:

```json theme={"system"}
{
  "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](mailto:support@whilter.ai) or explore more API references in the sidebar.