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:

{
    "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

{
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>",
    "Content-Type": "multipart/form-data"
}

Request Body

{
    "actionText": "Learn More",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "backgroundImage": "<PathToBackgroundImage>",
    "brandImage": "<PathToBrandImage>",
    "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)

{
    "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)

{
    "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

{
    "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

{
  "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<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.

---

Request Example (JSON)

Request Headers

{
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>",
    "Content-Type": "multipart/form-data"
}

Request Body

{
    "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": "<PathToBrandImage>",
    "backgroundImage": "<PathToBackgroundImage>"
}

---

Response Format

Success Response (HTTP 200)

{
    "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)

{
    "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

{
    "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

{
  "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

{
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>",
    "Content-Type": "application/json"
}

Query Parameters

{
    "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "imageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f"
}

---

Response Format

Success Response (HTTP 200)

{
    "$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

{
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>",
    "Content-Type": "application/json"
}

Query Parameters

{
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f"
}

---

Response Format

Success Response (HTTP 200)

[
    {
        "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 <YOUR_BEARER_TOKEN>
x-api-key	API key for client identification	<YOUR_API_KEY>
x-api-secret	API secret for secure access	<YOUR_API_SECRET>
Accept	Expected response format	application/json

---

Query Parameters

Parameter	Required	Description	Example Value
applicationId	Yes	ID of the application making the request	4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
taskId	Yes	Unique identifier for the specific task	f3008b9d-dba7-471f-abc5-624a9c7d60d4
imageRenderProcessId	Yes	ID of the image rendering process	db2ff597-6c13-41f6-b0d6-5d0032de035b
lowResolution	No	Indicates whether the image is in low resolution	false

---

Request Format

The request must include query parameters and required headers:

Request Headers

{
    "Accept": "application/json",
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>"
}

Request Query Parameters

{
    "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
    "taskId": "f3008b9d-dba7-471f-abc5-624a9c7d60d4",
    "imageRenderProcessId": "db2ff597-6c13-41f6-b0d6-5d0032de035b",
    "lowResolution": "false"
}

---

Example Requests

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 <token>
x-api-key: <your-api-key>
x-api-secret: <your-api-secret>
Accept: application/json

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 <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_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:

{
    "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:

{
    "$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:

{
    "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.

---