# 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`. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-docs.adcreative.ai/docs/features/adcreative-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.