> For the complete documentation index, see [llms.txt](https://api-docs.adcreative.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.adcreative.ai/docs/features/adcreative-api.md). # AdCreative API
## AdCreative API Documentation ### Overview 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: 1. **AdCreative Generation**: Create visually appealing advertisements based on client-provided inputs. 2. **Progress Tracking**: Monitor the generation progress of individual or application-wide tasks. 3. **AdCreative Editing**: Modifying selected AdCreatives from completed progress and regenerating them. 4. **AdCreative Download**: Download the generated AdCreative files. #### Important Note 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: ```json { "errors": { "engine: Active": [ "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f." ], "business: Active": [ "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-ac4f3a19e10981f5f4b5aa22ffd0d0f4-60f1194e0090da68-00" } } ``` To configure a Notification Channel, refer to the Notification API Documentation. *** ### Endpoints Overview #### **Generation/AdCreativesByKind** This endpoint generates AdCreatives based on the provided input parameters. It leverages AI capabilities to create marketing or campaign visuals tailored to client needs. #### **CheckUserProgress** This endpoint allows the client application to query the progress of generation tasks for a specific user. #### **CheckApplicationAllProgresses** This endpoint lists all the progress of the generation tasks initiated by the client application. #### **Edit/AdCreativesByTasks** 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. #### **Download** This endpoint enables downloading a generated AdCreative using its taskId. *** ## AdCreativesByKind Endpoint Documentation ### Endpoint Overview 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. #### HTTP Method and URL **POST** `/api/v1/Image/Generation/AdCreativesByKind` #### Authorization This endpoint requires a valid Bearer Token for authorization. ### Request Format The request must be sent as a `multipart/form-data`. Below is the detailed explanation of all the parameters: | Parameter | Type | Required | Description | | ------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------ | | **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. | ### Request Example (JSON) #### Request Headers ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "", "Content-Type": "multipart/form-data" } ``` #### Request Body ```json { "actionText": "Learn More", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "backgroundImage": "", "brandImage": "", "color1Hex": "#fc2c2c", "color2Hex": "#002c2c", "mainHeadline": "Introducing Our Latest Product", "punchline": "Revolutionizing the industry.", "renderKind": 1, "renderType": 2, "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "description": "A stunning new way to showcase your brand.", "buttonIconClass": "fa-solid fa-angle-right", "fontIdentifier": null, "color3Hex": "#cccccc" } ``` ### Response Format The response will return an object detailing the progress of the AdCreative generation. #### Success Response (HTTP 200) ```json { "messageType": "ImageGenerationProgress", "requestRenderState": 1, "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "2e1e071c-e0dd-4441-b83f-d389b1060b86", "totalTaskCount": 5, "completedTaskCount": 0, "progress": 0, "tasks": { "18222b27-8f3c-4370-b19b-e46a241bf113": 1, "839a6644-c252-4713-a85d-ef6fb058d4e8": 1, "f87ff39c-6e7f-4977-be29-43a2e6fcd4ca": 1, "5cccaa6b-7391-4b4a-976a-08e9e38ff400": 1, "3d4f24f5-630d-4d46-b5f7-3c73d6a6aaaf": 1 }, "renderKind": 1, "renderType": 2, "isSuccessful": true, "errorMessage": "" } ``` #### Error Responses **HTTP 400 (Bad Request)** ```json { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "Color1Hex": [ "The Color1Hex field is required." ], "BrandImage": [ "The BrandImage field is required." ] } } ``` **HTTP 404 Not Found** ```json { "errors": { "engine: Active": [ "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f." ], "business: Active": [ "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-ac4f3a19e10981f5f4b5aa22ffd0d0f4-60f1194e0090da68-00" } } ``` **HTTP 401 Unauthorized** ```json { "errors": { "business:": [ "Token is missing, invalid or ApplicationId is not found in the token." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 401, "detail": null, "instance": null, "extensions": { "traceId": "00-fc878634896257c5991ac5399ab6c46c-416e4be3606fdbaa-00" } } ``` ### Additional Notes 1. **Notification Requirement:** Ensure that an active notification channel is configured for the application before calling this endpoint. 2. **Validation:** All required fields must be provided, and files must meet the required formats. *** ## Editing/AdCreativesByTasks Endpoint Documentation ### Endpoint Overview 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. #### HTTP Method and URL **POST** `/api/v1/Image/Editing/AdCreativesByTasks` *** #### Authorization This endpoint requires a valid Bearer Token for authorization. ### Request Format The request must be sent as `multipart/form-data`. Below is the detailed explanation of all the parameters: | Parameter | Type | Required | Description | | ------------------- | ------------ | -------- | ----------------------------------------------------------------------------- | | **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` | 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. | *** ### Request Example (JSON) #### Request Headers ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "", "Content-Type": "multipart/form-data" } ``` #### Request Body ```json { "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "taskIds": [ "24929cc8-34da-455b-a4f1-61f895ac3a06", "e1ce6207-f817-40f4-ae6c-fe06a57577c1" ], "mainHeadline": "Main headline yeni", "punchline": "Punchline yeni", "actionText": "Action text yeni", "description": "The description is the magnificant. yeni", "buttonIconClass": "fa-solid fa-angle-right", "fontIdentifier": null, "color1Hex": "#fc2c2c", "color2Hex": "#002c2c", "color3Hex": "#cccccc", "brandImage": "", "backgroundImage": "" } ``` *** ### Response Format #### Success Response (HTTP 200) ```json { "messageType": "ImageGenerationProgress", "requestRenderState": 1, "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f", "totalTaskCount": 10, "completedTaskCount": 8, "progress": 80, "tasks": { "24929cc8-34da-455b-a4f1-61f895ac3a06": 1, "855c3f61-0f00-457a-81a0-b2c0653d2b21": 5, "e1ce6207-f817-40f4-ae6c-fe06a57577c1": 1, "0b7af445-2182-404c-abc5-1089eed36dcb": 5 }, "renderKind": 1, "renderType": 2, "isSuccessful": true, "errorMessage": "" } ``` *** #### Error Responses **HTTP 400 (Bad Request)** ```json { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "taskIds": [ "The TaskIds field is required." ] } } ``` **HTTP 404 Not Found** ```json { "errors": { "engine: Active": [ "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f." ], "business: Active": [ "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-ac4f3a19e10981f5f4b5aa22ffd0d0f4-60f1194e0090da68-00" } } ``` **HTTP 401 Unauthorized** ```json { "errors": { "business:": [ "Token is missing, invalid or ApplicationId is not found in the token." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 401, "detail": null, "instance": null, "extensions": { "traceId": "00-fc878634896257c5991ac5399ab6c46c-416e4be3606fdbaa-00" } } ``` *** ### Additional Notes 1. **Notification Requirement:** Ensure that an active notification channel is configured for the application before calling this endpoint. 2. **Validation:** All required fields must be provided, and files must meet the required formats. *** ## Documentation for CheckUserProgress and CheckApplicationAllProgresses ### Endpoint 1: CheckUserProgress #### Endpoint Overview 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. *** #### Request Format | Parameter | Type | Required | Description | | ------------------------ | ------ | -------- | ----------------------------------------------------------------------- | | **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** ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "", "Content-Type": "application/json" } ``` **Query Parameters** ```json { "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f" } ``` *** #### Response Format **Success Response (HTTP 200)** ```json { "$id": "1", "$values": [ { "$id": "2", "messageType": "ImageGenerationProgress", "requestRenderState": 5, "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f", "totalTaskCount": 10, "completedTaskCount": 10, "progress": 100, "tasks": { "$id": "3", "24929cc8-34da-455b-a4f1-61f895ac3a06": 5, "855c3f61-0f00-457a-81a0-b2c0653d2b21": 5, "e1ce6207-f817-40f4-ae6c-fe06a57577c1": 5, "0b7af445-2182-404c-abc5-1089eed36dcb": 5, "666aacbb-b390-4956-9f39-0a27285c23c6": 5, "35a4da04-8566-4d3e-ae96-6a7e3a2b6f37": 5, "21100ba8-f5b9-4791-a798-0f9b1805fbed": 5, "79a962b4-b663-4a4b-b756-03e3b6a65a06": 5, "d4138dc4-044c-4a37-b760-c3ac61b85e9d": 5, "141c2bdf-cfd4-499d-878e-d8f7157f4f96": 5 }, "renderKind": 1, "renderType": 2, "isSuccessful": true, "errorMessage": "" } ] } ``` **Error Responses** | HTTP Status | Error Message | Description | | ----------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | **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. | *** ### Endpoint 2: CheckApplicationAllProgresses #### Endpoint Overview 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. *** #### Request Format | Parameter | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------------------------------- | | **applicationId** | `Guid` | Yes | The unique identifier of the application whose progress is queried. | **Headers** ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "", "Content-Type": "application/json" } ``` **Query Parameters** ```json { "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f" } ``` *** #### Response Format **Success Response (HTTP 200)** ```json [ { "messageType": "ImageGenerationProgress", "requestRenderState": 1, "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "userId": "30430501-840a-3cbb-a1dd-b00f722bd79f", "imageRenderProcessId": "e68206ca-c739-188b-6ce3-5e45042b993e", "totalTaskCount": 5, "completedTaskCount": 4, "progress": 80, "tasks": { "taskId1": 1, "taskId2": 1 }, "renderKind": 1, "renderType": 16, "isSuccessful": true, "errorMessage": "" } ] ``` **Error Responses** | HTTP Status | Error Message | Description | | ----------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | **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. | *** ### Additional Notes 1. **Detailed Logs:** Ensure your application has logging enabled to capture any errors during the process. 2. **Validation:** Validate the `userId`, `imageRenderProcessId`, and `applicationId` before making API calls to avoid unnecessary errors. 3. **Error Trace:** Use the traceId in the response for debugging or reporting issues to support. *** ## Download Endpoint Documentation ### Endpoint Overview 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. *** ### HTTP Method and URL **Method**: `GET`\ **URL**: `/api/v1/Image/Generation/Download`\ **Full Path**: `https://api.adcreative.ai/api/v1/Image/Generation/Download` *** #### Authorization The following headers must be included for authentication and identification: | Header | Description | Example Value | | --------------- | --------------------------------- | ---------------------------- | | `Authorization` | Bearer token for authentication | Bearer `` | | `x-api-key` | API key for client identification | `` | | `x-api-secret` | API secret for secure access | `` | | `Accept` | Expected response format | `application/json` | *** ### Query Parameters
ParameterRequiredDescriptionExample Value
applicationIdYesID of the application making the request4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
taskIdYesUnique identifier for the specific taskf3008b9d-dba7-471f-abc5-624a9c7d60d4
imageRenderProcessIdYesID of the image rendering processdb2ff597-6c13-41f6-b0d6-5d0032de035b
lowResolutionNoIndicates whether the image is in low resolutionfalse
*** ### Request Format The request must include query parameters and required headers: #### Request Headers ```json { "Accept": "application/json", "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "" } ``` #### Request Query Parameters ```json { "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6", "taskId": "f3008b9d-dba7-471f-abc5-624a9c7d60d4", "imageRenderProcessId": "db2ff597-6c13-41f6-b0d6-5d0032de035b", "lowResolution": "false" } ``` *** ### Example Requests ```http GET /api/v1/Image/Generation/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=f3008b9d-dba7-471f-abc5-624a9c7d60d4&imageRenderProcessId=db2ff597-6c13-41f6-b0d6-5d0032de035b&lowResolution=false HTTP/1.1 Host: api.adcreative.ai Authorization: Bearer x-api-key: x-api-secret: Accept: application/json ``` ```bash curl --location 'https://api.adcreative.ai/api/v1/Image/Generation/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=f3008b9d-dba7-471f-abc5-624a9c7d60d4&imageRenderProcessId=db2ff597-6c13-41f6-b0d6-5d0032de035b&lowResolution=false' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer ' \\ --header 'x-api-key: ' \\ --header 'x-api-secret: ' ``` *** ### Response Formats The response will either return the image stream or an error. *** #### Successful Response **HTTP Status Code**: `200 OK`\ **Response Type**: `FileStream`\ **Details**: The requested image file stream will be directly downloaded. *** #### Authorization Error Response **HTTP Status Code**: `401 Unauthorized`\ **Response Body**: ```json { "errors": { "business:": [ "Token is missing, invalid or ApplicationId is not found in the token." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 401, "detail": null, "instance": null, "extensions": { "traceId": "00-b8c02b089b03e2d3cb45952dc9650566-853457d705e82d52-00" } } ``` *** #### Validation Error Response **HTTP Status Code**: `400 Bad Request`\ **Response Body**: ```json { "$id": "1", "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "$id": "2", "taskId": [ "The value 'f3008b9d-dba7-471f-abc5-624a9c7d60d' is not valid." ] }, "traceId": "00-009b6aa6671acaf79599957c34c9164b-08d5a70882602f88-00" } ``` *** #### Not Found Error Response **HTTP Status Code**: `404 Not Found`\ **Response Body**: ```json { "errors": { "engine: Generation/Download": [ "Image content not found." ], "business: Generation/Download": [ "Not found error occurred while getting original image content stream" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-51c724f54f0bf3aee0876d0f44d8e46b-72fbdb625616b668-00" } } ``` *** ### Error Notes * **400 Bad Request**: * Occurs when `taskId` or other parameters are invalid. * Ensure all query parameters are properly formatted. * **404 Not Found**: * No image content is found for the provided identifiers. * Verify that `applicationId`, `taskId`, and `imageRenderProcessId` are correct. * **401 Unauthorized**: * Bearer token is missing or invalid. * Ensure proper API key and secret are used in the headers. *** ### Additional Notes 1. **Incremental Tracking**: Every download increments the `DownloadCount` for both the task and the render process in the database. 2. **Validation**: Ensure that valid GUIDs are provided for both `taskId` and `imageRenderProcessId`. ***