AdCreative API
Last updated
Last updated
The AdCreative API enables client applications to leverage AI-powered technology to generate creative advertisements, marketing visuals, or campaign materials (AdCreatives). The API provides endpoints for the following functionalities:
AdCreative Generation: Create visually appealing advertisements based on client-provided inputs.
Progress Tracking: Monitor the generation progress of individual or application-wide tasks.
AdCreative Editing: Modifying selected AdCreatives from completed progress and regenerating them.
AdCreative Download: Download the generated AdCreative files.
Before initiating the AdCreative generation process, the client application must configure an active notification channel (e.g., Webhook, RabbitMQ). Without an active channel, AdCreative generation cannot proceed, and the API will return the following error:
To configure a Notification Channel, refer to the Notification API Documentation.
This endpoint generates AdCreatives based on the provided input parameters. It leverages AI capabilities to create marketing or campaign visuals tailored to client needs.
This endpoint allows the client application to query the progress of generation tasks for a specific user.
This endpoint lists all the progress of the generation tasks initiated by the client application.
This endpoint allows editing of selected AdCreatives within a completed progress. Edited AdCreatives are reintroduced into the generation process, and the progress is recalculated accordingly.
This endpoint enables downloading a generated AdCreative using its taskId.
This endpoint allows the generation of AdCreatives using specific parameters provided by the client. It is a critical operation in the AdCreative platform to generate AI-enhanced advertising materials such as banners, images, or other campaign-related visuals.
POST /api/v1/Image/Generation/AdCreativesByKind
This endpoint requires a valid Bearer Token for authorization.
The request must be sent as a multipart/form-data. Below is the detailed explanation of all the parameters:
actionText
string
Yes
The call-to-action text displayed on the AdCreative. Maximum 100 characters.
applicationId
Guid
Yes
The unique identifier of the application initiating the request.
backgroundImage
IFormFile
Yes
The background image for the AdCreative. Must be a valid image file.
brandImage
IFormFile
Yes
The brand logo image. Must be a valid image file.
color1Hex
string
Yes
Primary color in HEX format (e.g., #FFFFFF). Validates with a custom Color attribute.
color2Hex
string
Yes
Secondary color in HEX format.
mainHeadline
string
Yes
The main headline for the AdCreative. Maximum 255 characters.
punchline
string
Yes
The subtext or punchline for the AdCreative. Maximum 255 characters.
renderKind
integer
Yes
Type of render requested. Valid values: 0, 1, 2, 4, 8, 16, 31, 32, 64, 128, 256, 512, 992, 1023.
renderType
integer
Yes
Output format for the render. Valid values: 0, 1, 2, 4, 8, 16, 19, 32, 64, 100, 127, 128.
userId
Guid
Yes
The unique identifier of the user requesting the generation.
description
string
No
An optional description for the AdCreative. Maximum 1000 characters.
buttonIconClass
string
No
FontAwesome icon class for the button. Defaults to "fa-solid fa-angle-right".
fontIdentifier
string
No
Custom font identifier for the AdCreative.
color3Hex
string
No
Tertiary color in HEX format. Optional field.
The response will return an object detailing the progress of the AdCreative generation.
HTTP 400 (Bad Request)
HTTP 404 Not Found
HTTP 401 Unauthorized
Notification Requirement: Ensure that an active notification channel is configured for the application before calling this endpoint.
Validation: All required fields must be provided, and files must meet the required formats.
This endpoint allows for editing specific tasks within a completed progress of AdCreatives. By selecting tasks from a completed progress, clients can reintroduce them for re-generation, effectively rolling back the progress state and resuming the generation process from the adjusted point. For instance, if a progress contains 10 AdCreatives, and 2 of them are edited, these tasks are reintroduced into the generation process, adjusting the progress from 100% to 80% and allowing the completion process to proceed anew.
POST /api/v1/Image/Editing/AdCreativesByTasks
This endpoint requires a valid Bearer Token for authorization.
The request must be sent as multipart/form-data. Below is the detailed explanation of all the parameters:
applicationId
Guid
Yes
The unique identifier of the application initiating the request.
userId
Guid
Yes
The unique identifier of the user requesting the edit.
taskIds
List<Guid>
Yes
A list of task IDs selected for editing and re-generation.
mainHeadline
string
No
Optional new headline for the AdCreative. Maximum 255 characters.
punchline
string
No
Optional new punchline for the AdCreative. Maximum 255 characters.
actionText
string
No
Optional call-to-action text. Maximum 100 characters.
description
string
No
Optional new description for the AdCreative. Maximum 1000 characters.
buttonIconClass
string
No
FontAwesome icon class for the button. Defaults to "fa-solid fa-angle-right".
fontIdentifier
string
No
Optional custom font identifier for the AdCreative.
color1Hex
string
No
Optional primary color in HEX format (e.g., #FFFFFF).
color2Hex
string
No
Optional secondary color in HEX format.
color3Hex
string
No
Optional tertiary color in HEX format.
brandImage
IFormFile
No
Optional new brand logo image. Must be a valid image file.
backgroundImage
IFormFile
No
Optional new background image for the AdCreative. Must be a valid image file.
HTTP 400 (Bad Request)
HTTP 404 Not Found
HTTP 401 Unauthorized
Notification Requirement: Ensure that an active notification channel is configured for the application before calling this endpoint.
Validation: All required fields must be provided, and files must meet the required formats.
This endpoint retrieves the progress of AdCreative generation tasks initiated by a specific user. You can optionally filter results by ImageRenderProcessId to narrow down progress for a particular process.
HTTP Method and URL
GET /api/v1/Image/Generation/CheckUserProgress
Authorization
This endpoint requires:
Bearer Token for authentication.
API Key (x-api-key) and API Secret (x-api-secret) in the headers.
userId
Guid
Yes
The unique identifier of the user whose task progress is being queried.
imageRenderProcessId
Guid
No
The specific render process ID to filter tasks.
Headers
Query Parameters
Success Response (HTTP 200)
Error Responses
400
ImageRenderProcess(ImageRenderProcessId: N/A) was not found for the User: 2581c740-...
The requested ImageRenderProcessId or userId is invalid or does not exist.
401
"Token is missing, invalid or ApplicationId is not found in the token."
Authentication failure. The token is missing or invalid.
500
"An unexpected error occurred while checking image generation process."
Internal server error occurred while processing the request.
This endpoint retrieves the progress of all AdCreative generation tasks initiated under a specific application.
HTTP Method and URL
GET /api/v1/Image/Generation/CheckApplicationAllProgresses
Authorization
This endpoint requires:
Bearer Token for authentication.
API Key (x-api-key) and API Secret (x-api-secret) in the headers.
applicationId
Guid
Yes
The unique identifier of the application whose progress is queried.
Headers
Query Parameters
Success Response (HTTP 200)
Error Responses
400
"No running ImageGenerationProgress found for the ApplicationId: d5eabbb8-c0f6-4640-94fd..."
The requested applicationId is invalid or does not exist.
401
"Token is missing, invalid or ApplicationId is not found in the token."
Authentication failure. The token is missing or invalid.
500
"An unexpected error occurred while checking image generation process."
Internal server error occurred while processing the request.
Detailed Logs: Ensure your application has logging enabled to capture any errors during the process.
Validation: Validate the userId, imageRenderProcessId, and applicationId before making API calls to avoid unnecessary errors.
Error Trace: Use the traceId in the response for debugging or reporting issues to support.
The Download endpoint is used to retrieve the original image associated with a specific task and render process. This operation streams the image directly to the client.
GET /api/v1/Image/Generation/Download
This endpoint requires a valid Bearer Token along with x-api-key and x-api-secret headers for authorization.
taskId
Guid
Yes
The unique identifier of the task for which the image is being fetched.
imageRenderProcessId
Guid
Yes
The unique identifier of the render process associated with the task.
The request must include query parameters and required headers:
Request Headers
Request Query Parameters
Example Request
The response will either return the image stream or an error.
When the image is successfully retrieved, the server returns:
Content-Type: image/png
Body: The binary stream of the requested image.
HTTP 404 (Not Found)
HTTP 400 (Bad Request)
Incremental Tracking: Every download increments the DownloadCount for both the task and the render process in the database.
Validation: Ensure that valid GUIDs are provided for both taskId and imageRenderProcessId.
