# Create Access Token Source: https://developer.whilter.ai/api-reference/authorization-api/get-authorization-token POST /auth/token Authenticate using client credentials to obtain an access token # Cancel Task Source: https://developer.whilter.ai/api-reference/batch-media-api/cancel-batch-task POST /media/task/cancel/{taskId} Cancels an existing task by its ID # Get Task Status Source: https://developer.whilter.ai/api-reference/batch-media-api/check-status GET /media/task/status/{taskId} Retrieves the current status of a task by its ID # Create Task Source: https://developer.whilter.ai/api-reference/batch-media-api/create-batch-task POST /media/task/create Creates a new image processing task with specified parameters # Introduction Source: https://developer.whilter.ai/api-reference/introduction Welcome to the Charp.ai API Reference. This section provides detailed endpoint documentation, request/response schemas, and interactive examples for every available API. ## Authentication Before calling any API, you need to obtain an access token using your client credentials. The token is passed as a `Bearer` token in the `Authorization` header of all subsequent requests. Authenticate with your `client_id` and `client_secret` to receive a Bearer token *** ## Available APIs Create, manage, and monitor large-scale media generation tasks for batch campaigns Trigger on-the-fly personalized media generation from apps or chatbots in real time Enable AI-powered virtual garment try-on experiences with model and garment images *** ## Endpoint Overview ### Authorization API | Method | Endpoint | Description | | ------ | ------------- | ----------------------------------------------- | | `POST` | `/auth/token` | Obtain an access token using client credentials | ### Batch Media API | Method | Endpoint | Description | | ------ | ----------------------------- | ---------------------------------------- | | `POST` | `/media/task/create` | Create a new batch media generation task | | `POST` | `/media/task/cancel/{taskId}` | Cancel an in-progress batch task | | `GET` | `/media/task/status/{taskId}` | Check the status of a batch task | ### Realtime Media API | Method | Endpoint | Description | | ------ | ------------------------- | -------------------------------------------- | | `POST` | `/media/demo` | Generate personalized media in real time | | `GET` | `/status/{transactionId}` | Check the status of a realtime media request | ### Virtual Try-On API | Method | Endpoint | Description | | ------ | -------------------------- | ------------------------------------------------------------- | | `POST` | `/vton/request` | Submit a virtual try-on request with model and garment images | | `GET` | `/vton/status/{requestId}` | Retrieve the status and output of a try-on request | *** ## Common Response Codes | Code | Description | | ----- | ------------------------------------------- | | `200` | Request was successful | | `400` | Bad request — invalid or missing parameters | | `401` | Unauthorized — invalid or expired token | ## Need Help? If you need integration support, reach out to us at [support@whilter.ai](mailto:support@whilter.ai). # Get Media Status Source: https://developer.whilter.ai/api-reference/realtime-media-api/check-status GET /status/{transactionId} Retrieve the current status and URLs of a video generation request # Generate Media Source: https://developer.whilter.ai/api-reference/realtime-media-api/create-realtime-task POST /media/demo Create a personalized video generation request in real-time # Get Virtual Tryon Status Source: https://developer.whilter.ai/api-reference/virtual-tryon-api/get-tryon-status GET /vton/status/{requestId} Get Virtual Tryon Status # Create Virtual Tryon Request Source: https://developer.whilter.ai/api-reference/virtual-tryon-api/tryon-request POST /vton/request Create Virtual Tryon Request # Batch Media Generation Source: https://developer.whilter.ai/batch-media-api 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
with personalization fields
for Media (Image/Video) Client->>Client: Zip and name file %% Upload CSV Client->>SFTP: Upload zipped
campaign CSV file in sftp/in Client->>Media: Initiate task via
Task-API with
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 &
generate media per row Media->>S3: Store generated media S3-->>Media: Return Media URLs Media->>Media: Write Media URLs
into Output CSV %% Upload output Media->>SFTP: Upload Output CSV
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:////task ``` #### Request Headers: ```json theme={"system"} { "Authorization": "Bearer ", "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/` ```http theme={"system"} GET https:////task/status/ ``` #### Request Headers: ```json theme={"system"} { "Authorization": "Bearer " } ``` #### 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:///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 ", "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. # Introduction Source: https://developer.whilter.ai/introduction Our platform provides a suite of APIs designed to enable seamless creation and delivery of personalized media experiences at scale and in real time. ## Key APIs Covered * **Batch Media Generation**\ Process high-volume campaigns with ease. This API enables structured batch-based media generation — ideal for personalized images or videos delivered at scale. * **Scheduled Media Generation**\ Automate recurring high-volume campaigns through a file-based SFTP workflow. Upload structured data files to a secure SFTP server, and our system automatically processes them at scheduled intervals—requiring no direct API integration. * **Realtime Media Generation**\ Trigger dynamic, on-the-fly media generation from user-facing apps or chatbots. Perfect for instant, personalized video or image creation based on user input. * **Virtual TryOn**\ Bring interactive product experiences to life by allowing users to virtually try on items within your app. RESTful and easy to integrate. These APIs serve as the foundation for building personalized customer experiences that are timely, scalable, and engaging. > **More APIs:**\ > In addition to media generation APIs, this documentation will also include references to: > > * Authentication API > * Overall API Workflow Whether you’re building campaign tools, integrating with chat-based journeys, or enhancing product interactivity, our APIs are designed to empower your solutions. ## Getting Started The journey with our API begins with vendor registration, followed by authentication, and then interaction with our various API sets, including Campaign and Tools APIs. Process large-scale personalized media campaigns using structured batch workflows Automate high-volume campaigns through a scheduled file-based SFTP workflow Instantly generate personalized videos in real-time from apps or chatbots Try garments virtually on model photos using AI-powered fitting technology Understand the end-to-end API workflow and how to integrate efficiently Securely authenticate and authorize access using API keys and tokens ## Next Steps To begin using our APIs, proceed to the API Workflow section for a detailed breakdown of the available endpoints and their functionalities. # Realtime Media Generation Source: https://developer.whilter.ai/realtime-media-api Generate personalized videos in real-time via Whilter.AI API # Overview Whilter.AI’s **Realtime Media API** allows client systems (like chatbots or apps) to trigger personalized video generation dynamically. This API is optimized for rapid, transactional media creation based on real-time user input or actions. ```mermaid theme={"system"} sequenceDiagram participant WhatsApp Chatbot participant Client/Vendor Application participant Whilter.AI WhatsApp Chatbot->>Client/Vendor Application: Conversation Start ongoing... Note right of WhatsApp Chatbot: ...closure with enough inputs (text/image/video) Client/Vendor Application->>Whilter.AI: Get Token Whilter.AI-->>Client/Vendor Application: Token Client/Vendor Application->>Whilter.AI: Send Video Create Request Note right of Whilter.AI: Video Generation Whilter.AI-->>Client/Vendor Application: Call Webhook API (with Video URL) Client/Vendor Application->>WhatsApp Chatbot: Send WhatsApp Message with Video Embedded ``` *** ## Step 1: Get Access Token All API calls require a valid access token. **GET** `/getToken` ```http theme={"system"} GET https:///getToken?clientId=&clientSecret= ``` > Request must be made from a **whitelisted IP**. **Sample Response:** ```json theme={"system"} { "access_token": "", "expires_in": 86400, "token_type": "Bearer" } ``` *** ## Step 2: Trigger New Video Generation **POST** `/video/demo` ```http theme={"system"} POST https:///video/demo ``` **Headers:** * `x-api-key: ` * `Authorization: Bearer ` **Request Body:** ```json theme={"system"} { "client-request-id": "unique-id", "customer-id": "customer-id", "use-case-id": "template-id", "user-id": "user-id", "reference-record-id": "optional", "phrase-texts": ["Text A", "Text B"], "image-texts": ["Text A", "Text B"], "video-texts": ["Text A", "Text B"], "image-urls": ["https://s3.amazonaws.com/img1.jpeg"], "video-urls": ["https://s3.amazonaws.com/video1.mp4"] } ``` **Response:** ```json theme={"system"} { "status": "SUCCESS", "message": "Request accepted", "client-request-id": "unique-id", "whilter-request-id": "generated-id" } ``` *** ## Step 3: Check Video Status **GET** `/status/` ```http theme={"system"} GET https:///status/ ``` **Headers:** * `x-api-key: ` * `Authorization: Bearer ` **Response:** ```json theme={"system"} { "status": "SUCCESS", "message": null, "video-url": "https://cdn.whilter.ai/video.mp4", "image-url": "https://cdn.whilter.ai/image.jpg" } ``` > Note: `video-url` may initially be null. You can poll until the video is ready. *** ## Optional: Webhook Notification (Recommended) You may provide a webhook endpoint to receive video URLs automatically when the video is ready. **POST** `/video-push-endpoint` ```json theme={"system"} { "client-request-id": "unique-id", "user-id": "user-id", "video-url": "https://cdn.whilter.ai/video.mp4" } ``` **Suggested Response:** ```json theme={"system"} { "client-request-id": "unique-id", "status": "202" } ``` *** ## Error Handling | Error Code | Description | Suggested Action | | ---------- | ------------------ | ---------------------------------------- | | 400 | Bad Request | Check input JSON or parameters | | 404 | Endpoint Not Found | Check API URL | | 500 | Server Error | Retry after some time or contact support | ## API Reference To explore detailed endpoints and example requests, see the [Realtime Media API references](/api-reference/realtime-media-api/create-realtime-task). *** Need help integrating? [Contact us](mailto:support@whilter.ai) or explore more API references in the sidebar. # Schedule Media Generation Source: https://developer.whilter.ai/schedule-media-api Learn how to generate and deliver large-scale personalized media using Whilter.AI's schedule-based batch workflow. # Overview Whilter.AI’s **Schedule-Based Media** Integration allows clients to generate and deliver large-scale personalized images and videos via a structured, scheduled batch workflow, ensuring efficient and reliable media generation. *** ## High-Level Integration Flow ```mermaid theme={"system"} sequenceDiagram participant Client as Client System participant SFTP as Client SFTP Server participant Storage as Client S3 Bucket participant Media as Whilter Media Pipeline %% Step 1: Prepare Campaign Data Client->>Client: (1) Prepare campaign CSV
with personalization fields for Media (Image/Video) Client->>Client: (1) Zip campaign file %% Step 2: Upload to SFTP Client->>SFTP: (2) Upload zipped campaign CSV
to sftp/in Note over SFTP,Media: (3) Scheduled pickup (time-based) %% Step 3: Scheduled Processing & Output Delivery Media->>SFTP: (3) Check for new campaign files SFTP-->>Media: (3) Campaign file available Media->>SFTP: (3) Download zipped CSV SFTP-->>Media: (3) Deliver file Media->>Media: (3) Unzip, validate CSV
Generate media per row Media->>Storage: (3) Store generated media Storage-->>Media: (3) Return media URLs Media->>Media: (3) Write media URLs
into Output CSV Media->>SFTP: (3) Upload output CSV
to sftp/out %% Step 4: Completion Notification (Optional) Media-->>Client: (4) 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 File to SFTP Upload the ZIP file to the designated **input location** (e.g., `sftp/in`) shared during onboarding. You only need to upload the file once — **no API trigger is required**. *** ### Step 3: Scheduled Processing & Output Delivery * At the configured schedule, the system automatically checks for new files. * If a new file is detected: * The file is downloaded from the input location. * Data is unzipped and validated. * Media is generated for each row in the CSV. * Generated media files are stored securely in **Client S3 bucket**. * An output CSV is created containing: * Original identifiers * Generated media URLs * The output CSV is uploaded to the defined output location (e.g., `sftp/out`). *** ### Step 4: Completion Notification (Optional) * The client can provide a callback API. * Once processing is completed: * Our system sends a completion status to the callback API. * The client must whitelist our IPs for callback access. *** ## 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. *** For integration assistance, [Contact us](mailto:support@whilter.ai). # Virtual TryOn Source: https://developer.whilter.ai/virtual_tryon_api # Overview The Virtual TryOn API provides developers with the capability to integrate our try-on model directly into their applications. Built on a RESTful architecture, it currently supports only HTTP endpoints. ## Base URL The base URL for the Virtual TryOn API is: ```bash theme={"system"} https://vton/request ``` [Go to the API reference](/api-reference/virtual-tryon-api/tryon-request) ## Authentication Access to the Virtual TryOn API is secured through the use of API keys. ### API Key Usage Include your API key in the request headers: ```http theme={"system"} Authorization: Bearer YOUR_API_KEY ``` ## Error Handling The API uses conventional HTTP response codes to indicate success or failure: | Code | Description | | ---- | ------------------------------------------------ | | 200 | Success - Request completed successfully | | 400 | Bad Request - Invalid parameters or missing data | | 401 | Unauthorized - Invalid or missing API key | *** # API Parameters Guide ## Model Image **image URL | base64** `model-image` refers to the source image of the individual on whom the virtual try-on will be applied. This image can be submitted either as a publicly accessible URL or a base64-encoded string. Model Image Example ## Garment Image **image URL | base64** `garment-image` is the visual representation of the clothing item intended for virtual try-on with the `model-image`. You can provide this input either as a direct image URL or as a base64-encoded string. Garment Image Example Virtual Tryon accepts multiple garment photo formats including flat-lay, ghost mannequin, or model-worn images. **Garment Fit Examples** ## Category **string** `category` identifies the type of garment present in the `garment-image`. This guides the virtual try-on engine in selecting the appropriate region to apply the clothing. For images with multiple items (e.g., top and bottom), use this to prioritize the desired garment. Default: `auto` — automatically infers the garment type. | Value | Description | | ---------- | --------------------------------------------- | | auto | Automatically determines the garment category | | tops | Shirts, blouses, t-shirts | | bottoms | Pants, jeans, skirts | | one-pieces | Dresses, jumpsuits | Garment Photography Quality Spectrum *** ## Mode **string** `mode` determines the balance between processing speed and output quality. | Mode | Description | | ----------- | ------------------------------------------------------------------ | | performance | Optimized for speed; fastest response time (\~2-3s) | | balanced | A compromise between speed and quality (\~3-5s) | | quality | Prioritizes high-quality results; takes longer to process (\~5-8s) | ## Moderation Level **'conservative' | 'permissive' | 'none'** `moderation_level` controls how strictly the API filters garment images for content sensitivity. The default is `permissive`. * `conservative`: Filters out revealing garments. Recommended for modesty-sensitive use cases. * `permissive`: Allows most garments including swimwear and underwear, while rejecting explicit nudity. * `none`: Disables all content filtering. Use with caution. ## Segmentation Free **boolean** `segmentation_free` controls whether the system skips explicit garment segmentation. * `true`: Enables direct garment fitting without isolating clothing. * `false`: Enforces clothing segmentation. Use if artifacts from the original garments interfere with results. ## Output Format **'png' | 'jpeg'** `output_format` defines the desired image format for the generated try-on result. * `png`: High-quality output with no compression loss. * `jpeg`: Faster response with mild compression. Better for real-time use. ## API Reference To explore detailed endpoints and example requests, see the [Virtual TryOn API references](/api-reference/virtual-tryon-api/tryon-request). ***