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:

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.

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

An optional description for the AdCreative. Maximum 1000 characters.

buttonIconClass

string

FontAwesome icon class for the button. Defaults to "fa-solid fa-angle-right".

fontIdentifier

string

Custom font identifier for the AdCreative.

color3Hex

string

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

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.

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

Optional new headline for the AdCreative. Maximum 255 characters.

punchline

string

Optional new punchline for the AdCreative. Maximum 255 characters.

actionText

string

Optional call-to-action text. Maximum 100 characters.

description

string

Optional new description for the AdCreative. Maximum 1000 characters.

buttonIconClass

string

FontAwesome icon class for the button. Defaults to "fa-solid fa-angle-right".

fontIdentifier

string

Optional custom font identifier for the AdCreative.

color1Hex

string

Optional primary color in HEX format (e.g., #FFFFFF).

color2Hex

string

Optional secondary color in HEX format.

color3Hex

string

Optional tertiary color in HEX format.

brandImage

IFormFile

Optional new brand logo image. Must be a valid image file.

backgroundImage

IFormFile

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

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.

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

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

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.

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

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

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.

PreviousNotification Message Types NextImage Upscaler API

Last updated 5 months ago