# Introduction

AdCreative.ai API empowers hand-selected enterprises with proprietary AI technology to effortlessly generate high-performing, conversion-optimized ad assets, saving time and driving impactful results.

#### **What Makes AdCreative.ai API Unique?**

AdCreative.ai API stands apart as a premier solution for creating ad assets, powered by proprietary AI models that deliver unparalleled results. Designed for hand-selected enterprises, this exclusive API transforms ad creation into an effortless, data-driven process. From concept to execution, our technology ensures your visuals are not only high-performing and conversion-optimized but also save significant time and resources, enabling your team to focus on scaling impact.

If you’re interested in accessing our API, visit our [enterprise page](https://www.adcreative.ai/enterprise) to get in touch with us and discover how AdCreative.ai can redefine your advertising strategies.

***

#### **Current Features**

* **AdCreative API**: Gain access to our proprietary AI model that powers the Ad Creative feature on our platform. Generate hundreds of high-converting visuals per second in multiple sizes, optimized for web and print, ensuring exceptional quality and consistency at any resolution.

***

#### **Coming Soon**

* **Product Photoshoot API**: Elevate your product photos with our award-winning AI feature, transforming them into professional-grade product shoots that captivate your audience and drive engagement.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Authentication</strong></td><td><a href="https://1994826232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwTYepDyTMpGFxRZfslZA%2Fuploads%2FRP0J02nQaKmw95mSRVFv%2FFrame%204.png?alt=media&amp;token=317d10c2-1333-4cc9-a942-753ca56dce01">Frame 4.png</a></td><td><a href="https://api-docs.adcreative.ai/docs/getting-started/authentication">Authentication</a></td></tr><tr><td><strong>Error Handling</strong></td><td><a href="https://1994826232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwTYepDyTMpGFxRZfslZA%2Fuploads%2FPqujuO89qMB6zuBYOXT4%2FFrame%202.png?alt=media&amp;token=e70e4f5c-e5b5-44ae-bfde-d3c073a06861">Frame 2.png</a></td><td><a href="https://api-docs.adcreative.ai/docs/getting-started/error-handling">Error Handling</a></td></tr><tr><td><strong>AdCreative API</strong></td><td><a href="https://1994826232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwTYepDyTMpGFxRZfslZA%2Fuploads%2F6azmTmJsMhVCYHbBeZEw%2FFrame%208.png?alt=media&amp;token=f5fddd45-9f14-4c60-96e2-951970796d67">Frame 8.png</a></td><td><a href="https://api-docs.adcreative.ai/docs/features/adcreative-api">AdCreative API</a></td></tr></tbody></table>


# Core Capabilities

### 🎯 What **AdCreative** API Is

The AdCreative API is a **domain-agnostic**, high-performance service designed to **generate and deliver creative assets**, including images and text. It runs independently of the main AdCreative platform — with its own services, database, codebase, and operational logic.

It is used by both **internal** and **external** customers and provides a flexible, scalable foundation for asset generation needs.

***

### 🚫 What **AdCreative API** Is Not

* This API **does not integrate** with the AdCreative platform out-of-the-box.
* It **does not support** features like `Project`, `Customer`, `Brand`, or `Package`, which are specific to AdCreative UI.
* It **does not store** business-domain data (e.g., `clientName`, `campaignId`, `billboardSpec`).
* It **does not support** third-party ad network integrations like Google Ad Manager (GAM).
* It **cannot access** assets created through the AdCreative frontend unless a **custom bridge** is implemented.

***

### 🔍 Architectural Principles

To preserve purity and scalability, the API:

* Is **stateless** and **agnostic** to any specific business logic.
* Only recognizes two concepts for access control:
  1. `ApplicationId` (Integrator)
  2. `UserId` (optional sub-user per integrator)

It avoids tight coupling by **not embedding metadata** from integrators such as:

* Brand, Project, Package
* Billboard, Campaign, Spec
* Custom integrator client fields

If needed, integrators can handle mapping by correlating the `RenderProcessId` returned from the API with their own internal user IDs.

> Also, a quick note regarding the UserId:
>
> * If you’re generating images for different sub-users, you can differentiate them using distinct UserId values and filter requests based on these values.
> * If you don’t have a sub-users system, you can use a fixed UserId (also you can generate your own userID).
> * The UserId helps track and distinguish requests if you’re generating images for different sub-users.

***

### ⚙️ Basic Flow to Get Started

> While each generation feature may involve its own logic or additional inputs, the following three example endpoints are **consistently used across all generation workflows**:

* `POST /api/v1/Image/ProductGeneration/AdCreative`
* `POST /api/v1/Image/ProductGeneration/CheckUserProgress`
* `POST /api/v1/Image/ProductGeneration/Download`

These serve as the core flow for initiating generation, tracking its progress, and retrieving final results.

#### 1. 🔐 Generate an Access Token

* Endpoint: `POST /api/v1/Authorization/GenerateJwtToken`
* Tokens are generated using your `JwtPrivateKey`, `ApplicationId`.

> Using our Postman collection? No need to copy/paste — the token is auto-assigned via pre-request scripts.

***

#### 2. 🎨 Start a Generation Task

Trigger an asset generation via feature-specific endpoints, such as:

* `POST /api/v1/Image/Generation/AdCreativesByKind`
* `POST /api/v1/Image/BackgroundRemoving/AdCreative`

***

#### 3. 🔄 Track Progress

* Endpoint: `POST /api/v1/Image/Generation/CheckUserProgress`
* When `progress == 100`, `isSuccessful == true`, and all `renderState == 5` → your job is complete.

***

#### 4. 📦 Download Results

* Endpoint: `POST /api/v1/Image/Generation/Download`
* Input: list of `taskIds`

***

### 📣 Webhook Notifications

Enable real-time updates by setting a webhook:

* `POST /api/v1/Notification/ChannelConfiguration/WebHook` to create
* `PUT /api/v1/Notification/ChannelConfiguration/WebHook` to update
* Configure retry behavior: `RetryCount`, `ExponentialBackoffFactor`

#### Webhook Events

* **Progress Start**: job begins
* **Task Complete**: per image
* **Progress Complete**: full batch ready

Check configuration:

* `GET /Notification/ChannelConfiguration/All`
* `GET /Notification/ChannelConfiguration/Active`

***

### 🧪 Ready-To-Test: Postman Setup

To simplify integration testing:

* We provide a **Postman Collection** with all endpoints
* A **Postman Environment** with credentials (`X-API-KEY`, `X-API-SECRET`, `JwtPrivateKey`, `ApplicationId`, `UserId`)
* After importing, you can send API requests immediately — no setup required.

***

### 🧭 Supported Features

* **Image Processing**:
  * Background Removal
  * Upscaling
  * Face Enhancement
  * SVG-based Batch Generation
  * Stock/Product Image Generation
* **Text Generation**:
  * Website Scanner
  * Ad Text Generator

***

### ✅ Design Do’s & Don’ts

| Allowed                     | Not Allowed                                 |
| --------------------------- | ------------------------------------------- |
| Stateless, clean generation | Business-specific coupling (e.g., brandId)  |
| Integrator-level scoping    | Campaign/project storage in API             |
| Multi-feature reuse         | Metadata mixing from 3rd-party systems      |
| Webhook extensibility       | Dependency on external ad-serving platforms |

***

### 🚫 Why Domain Data Must Stay Out

Embedding metadata such as `clientId`, `projectId`, `safeZoneId` directly in the API would:

* Tie the API to client-specific implementations
* Break portability across partners
* Hurt long-term maintainability

Instead, integrators should map responses (e.g., `RenderProcessId`) with their own systems externally.

***

### 📚 Next Steps

Explore the full API documentation at:

👉 <https://api-docs.adcreative.ai/docs>


# asdsa

asdsadasd


# Authentication

## API Authorization Documentation

The API Authorization includes endpoints for generating and refreshing JWT tokens. These endpoints are essential for secure and authenticated access to other API functionalities.

***

### 1. Generate JWT Token

#### Endpoint:

```
POST /api/v1/Authorization/GenerateJwtToken
```

#### Description:

Generates a JWT token for a specified application. The token includes an `accessToken` and a `refreshToken`, which can be used for authentication and token refresh operations.

#### Request Headers:

* `Content-Type: application/json; x-api-version=1.0`
* `Accept: application/json`

#### Request Body:

```json
{
  "applicationId": "urn:uuid:91c698db-5cbe-0f55-915e-bd64d5178337",
  "jwtPrivateKey": "85896144dda1ff0b68fce638a221a7e824720e3622be630ff7c51ae94978c3b482d66886aecbb56469bbf990719c1e11b5a811ed6663a4915f4e34df486866d2"
}
```

| **Field**       | **Type** | **Description**                                  |
| --------------- | -------- | ------------------------------------------------ |
| `applicationId` | `string` | The unique identifier (UUID) of the application. |
| `jwtPrivateKey` | `string` | The private key used to sign the JWT.            |

#### Response:

* **Status 200 OK**

```json
{
  "$id": "1",
  "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessTokenExpiration": "2024-12-20T11:57:50.974699Z",
  "refreshToken": "OjKkePJHJOtX6wPl8S88U6da4XiZrjqfBXBtmOpQXiE=",
  "refreshTokenExpiration": "2024-12-27T11:57:50.974699Z"
}
```

| **Field**                | **Type**   | **Description**                                                    |
| ------------------------ | ---------- | ------------------------------------------------------------------ |
| `applicationId`          | `string`   | The unique identifier (UUID) of the application.                   |
| `accessToken`            | `string`   | The JWT access token for authentication.                           |
| `accessTokenExpiration`  | `datetime` | Expiration date and time for the `accessToken`.                    |
| `refreshToken`           | `string`   | Token used to obtain a new `accessToken` without logging in again. |
| `refreshTokenExpiration` | `datetime` | Expiration date and time for the `refreshToken`.                   |

#### Error Responses:

* **Status 400 Bad Request**
  * Invalid input data or missing required fields.
* **Status 500 Internal Server Error**
  * Server-side error during token generation.

***

### 2. Refresh JWT Token

#### Endpoint:

```
POST /api/v1/Authorization/RefreshJwtToken
```

#### Description:

Refreshes an expired JWT access token using a valid `refreshToken`.

#### Request Headers:

* `Content-Type: application/json; x-api-version=1.0`
* `Accept: application/json`

#### Request Body:

```json
{
  "applicationId": "d7f1bd96-8a69-6cf1-2f8f-bf4485909cc9",
  "jwtPrivateKey": "adipisicing labore occaecat quis",
  "refreshToken": "cupidatat"
}
```

| **Field**       | **Type** | **Description**                                     |
| --------------- | -------- | --------------------------------------------------- |
| `applicationId` | `string` | The unique identifier (UUID) of the application.    |
| `jwtPrivateKey` | `string` | The private key used to sign the JWT.               |
| `refreshToken`  | `string` | The token used to refresh the expired access token. |

#### Response:

* **Status 200 OK**

```json
{
  "$id": "1",
  "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessTokenExpiration": "2024-12-20T11:28:25.452242Z",
  "refreshToken": "KusyuOxD5xg7rmWEdJ+iPN8NRkatb1bRsCuQYqpzXq0=",
  "refreshTokenExpiration": "2024-12-27T11:28:25.452242Z"
}
```

| **Field**                | **Type**   | **Description**                                              |
| ------------------------ | ---------- | ------------------------------------------------------------ |
| `applicationId`          | `string`   | The unique identifier (UUID) of the application.             |
| `accessToken`            | `string`   | The refreshed JWT access token for authentication.           |
| `accessTokenExpiration`  | `datetime` | Expiration date and time for the refreshed `accessToken`.    |
| `refreshToken`           | `string`   | Token used to obtain another new `accessToken` if necessary. |
| `refreshTokenExpiration` | `datetime` | Expiration date and time for the new `refreshToken`.         |

#### Error Responses:

* **Status 400 Bad Request**

  * Invalid input data or missing required fields.

  ```json
  {
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-131a39782d3aa54ef0cfae62c715a4e2-61df78abdb62e43d-00",
    "errors": {
        "model": [
            "The model field is required."
        ],
        "$.applicationId": [
            "The JSON value could not be converted to System.Guid. Path: $.applicationId | LineNumber: 1 | BytePositionInLine: 56."
        ]
    }
  }
  ```
* **Status 401 Unauthorized**

  * Invalid or expired refresh token.

  ```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"
    }
  }
  ```
* **Status 500 Internal Server Error**

  * Server-side error during token refresh.

  ```json
  {
      "errors": {
          "business:": [
              "InvokeAsync: Authorization service configuration error."
          ]
      },
      "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
      "title": "An unexpected error occurred.",
      "status": 500,
      "detail": null,
      "instance": null,
      "extensions": {
          "traceId": "00-914cddf34585cf2527567899edf9f640-4fa7d7aed5c16373-00"
      }
  }
  ```


# Notifications

## Notification API Documentation

### Overview

The notification mechanism in our API is a crucial component for tracking the progress and outcomes of **Image Generation Tasks**. Notifications are essential for receiving feedback on task statuses and ensuring seamless communication between the API and client applications.

#### Why Notifications Are Important

inNotification channels are vital because they provide feedback on the results of image generation tasks. Before using the API, at least one notification channel must be configured from the available types (webhook or RabbitMQ). Among these, **webhook is recommended**, as it aligns with our internal solutions.

Without an active notification channel, a client application **cannot initiate any image generation requests** and will encounter 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"
    }
}
```

#### Notification Channel Features

When defining notification channels, it is optional to include the generated image data in the notification message content. Alternatively, the notification can simply provide task completion updates.

* **Important**: If the parameter `includeImageData` is set to `true`, the generated image data will be included in the notification message content. Otherwise, the notification will provide only task completion updates without including the image data.

A client application can define multiple notification channels of different types (webhook, RabbitMQ).

#### Task Notifications

The API sends two types of notifications:

1. An **"Image Generation Task Completed"** message when an individual task is finished.
2. An **"Image Generation Progress"** message when all tasks are completed.

#### Creating, Updating, and Managing Notifications

Using the provided endpoints, a client application can:

* Create notification channels
* Update notification channels
* Delete notification channels
* List all or active notification channels defined for the client application

#### Authentication Requirements

Each request made by a client application to the API must include:

* A valid JWT token
* `x-api-key` and `x-api-secret` values defined by AdCreative and provided to the client application. These values also carry information about the API usage credits.

If these authentication values are missing, the following error will be returned:

```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"
  }
}
```

This section provides a foundational understanding of how the notification mechanism operates and the prerequisites for its effective use. The next section will detail the available endpoints, including their request and response structures.

### Notification Query Endpoints

#### 1. Get All Notification Channel Configurations

**Endpoint**

`GET /api/v1/Notification/ChannelConfiguration/All`

**Description**

Retrieves a list of all notification channel configurations associated with a specific application.

**Request**

```http
GET /api/v1/Notification/ChannelConfiguration/All?applicationId={applicationId} HTTP/1.1
Host: localhost:9061
Accept: application/json
```

**Query Parameters**

* `applicationId` (required): The unique identifier of the application.

**Example Request**

```http
GET /api/v1/Notification/ChannelConfiguration/All?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f
```

**Example Response**

```json
[
  {
    "id": "e12fb790-ab01-4ae8-9a5a-f996579aaabf",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 2,
    "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test/\",\"Username\":\"guestRabbit\",\"Password\":\"2w3e3e4r5t\",\"QueueName\":\"queueTest\"}",
    "notificationChannelConfiguration": {
      "isActive": false,
      "includeImageData": true,
      "notificationChannel": 2
    },
    "isActive": false,
    "includeImageData": true,
    "createdAt": "2024-07-17T09:25:58.642536Z",
    "updatedAt": "2024-07-17T09:25:58.642537Z"
  }
]
```

***

#### 2. Get Active Notification Channel Configurations

**Endpoint**

`GET /api/v1/Notification/ChannelConfiguration/Active`

**Description**

Retrieves a list of active notification channel configurations for a specific application.

**Request**

```http
GET /api/v1/Notification/ChannelConfiguration/Active?applicationId={applicationId} HTTP/1.1
Host: localhost:6061
Accept: application/json
```

**Query Parameters**

* `applicationId` (required): The unique identifier of the application.

**Example Request**

```http
GET /api/v1/Notification/ChannelConfiguration/Active?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f
```

**Example Response (Active Notification Found)**

```json
{
  "$id": "1",
  "$values": [
    {
      "id": "c8409979-12ae-4608-8b2c-70c1d7eae696",
      "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
      "channel": 0,
      "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://example.com/webhook\",\"RetryCount\":5,\"ExponentialBackoffFactor\":2.0}",
      "notificationChannelConfiguration": {
        "isActive": true,
        "includeImageData": true,
        "notificationChannel": 0
      },
      "isActive": true,
      "includeImageData": true,
      "createdAt": "2024-12-20T18:24:23.141247Z",
      "updatedAt": "2024-12-20T18:24:23.141432Z"
    }
  ]
}
```

**Example Response (No Active Notification 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
}
```

***

#### 3. Get Specific Notification Channel Configuration

**Endpoint**

`GET /api/v1/Notification/ChannelConfiguration`

**Description**

Retrieves a specific notification channel configuration by its configuration ID.

**Request**

```http
GET /api/v1/Notification/ChannelConfiguration?applicationId={applicationId}&configurationId={configurationId} HTTP/1.1
Host: localhost:6061
Accept: application/json
```

**Query Parameters**

* `applicationId` (required): The unique identifier of the application.
* `configurationId` (required): The unique identifier of the configuration.

**Example Request**

```http
GET /api/v1/Notification/ChannelConfiguration?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f&configurationId=c8409979-12ae-4608-8b2c-70c1d7eae696
```

**Example Response**

```json
{
  "id": "c8409979-12ae-4608-8b2c-70c1d7eae696",
  "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
  "channel": 0,
  "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://example.com/webhook\",\"RetryCount\":3,\"ExponentialBackoffFactor\":2.0}",
  "notificationChannelConfiguration": {
    "isActive": true,
    "includeImageData": true,
    "notificationChannel": 0
  },
  "isActive": true,
  "includeImageData": true,
  "createdAt": "2024-12-20T18:24:23.141247Z",
  "updatedAt": "2024-12-20T18:47:12.438504Z"
}
```

***

#### 4. Delete Notification Channel Configuration

**Endpoint**

`DELETE /api/v1/Notification/ChannelConfiguration`

**Description**

Deletes a specific notification channel configuration by its configuration ID.

**Request**

```http
DELETE /api/v1/Notification/ChannelConfiguration?applicationId={applicationId}&configurationId={configurationId} HTTP/1.1
Host: localhost:6061
Accept: application/json
```

**Query Parameters**

* `applicationId` (required): The unique identifier of the application.
* `configurationId` (required): The unique identifier of the configuration.

**Example Request**

```http
DELETE /api/v1/Notification/ChannelConfiguration?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f&configurationId=c8409979-12ae-4608-8b2c-70c1d7eae696
```

**Example Response**

```json
true
```

***

This section provides detailed documentation for the RabbitMQ and WebHook notification configuration endpoints. These endpoints allow client applications to configure notification channels for receiving task completion updates.

***

### **RabbitMQ Endpoints**

**POST /api/v1/Notification/ChannelConfiguration/RabbitMQ**

**Description**\
Creates a new RabbitMQ notification channel configuration for a specified application.

**Request**

* **URL**:\
  `/api/v1/Notification/ChannelConfiguration/RabbitMQ`
* **Query Parameters**:

  ```json
  {
    "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099"
  }
  ```
* **Headers**:

  ```json
  {
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>"
  }
  ```
* **Body** *(form-data)*:

  ```json
  {
    "isActive": true,
    "password": "securePassword123",
    "queueName": "TaskQueue",
    "username": "admin",
    "url": "amqp://localhost/Test",
    "includeImageData": true
  }
  ```

**Example Response**

```json
{
    "id": "4d082fcb-2632-47c3-ac16-b92081801c2c",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 2,
    "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test\",\"Username\":\"admin\",\"Password\":\"securePassword123\",\"QueueName\":\"TaskQueue\"}",
    "isActive": true,
    "includeImageData": true,
    "createdAt": "2024-12-20T18:44:43.278369Z",
    "updatedAt": "2024-12-20T18:44:43.278369Z"
}
```

***

**PUT /api/v1/Notification/ChannelConfiguration/RabbitMQ**

**Description**\
Updates an existing RabbitMQ notification channel configuration.

**Request**

* **URL**:\
  `/api/v1/Notification/ChannelConfiguration/RabbitMQ`
* **Query Parameters**:

  ```json
  {
    "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099",
    "configurationId": "4d082fcb-2632-47c3-ac16-b92081801c2c"
  }
  ```
* **Headers**:

  ```json
  {
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>"
  }
  ```
* **Body** *(form-data)*:

  ```json
  {
    "isActive": true,
    "password": "securePassword123",
    "queueName": "TaskQueue",
    "username": "admin",
    "url": "amqp://localhost/Test",
    "includeImageData": true
  }
  ```

**Example Response**

```json
{
    "id": "4d082fcb-2632-47c3-ac16-b92081801c2c",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 2,
    "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test\",\"Username\":\"admin\",\"Password\":\"securePassword123\",\"QueueName\":\"TaskQueue\"}",
    "isActive": true,
    "includeImageData": true,
    "createdAt": "2024-12-20T18:44:43.278369Z",
    "updatedAt": "2024-12-20T18:46:09.637558Z"
}
```

***

### **WebHook Endpoints**

**POST /api/v1/Notification/ChannelConfiguration/WebHook**

**Description**\
Creates a new WebHook notification channel configuration for a specified application.

**Request**

* **URL**:\
  `/api/v1/Notification/ChannelConfiguration/WebHook`
* **Query Parameters**:

  ```json
  {
    "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099"
  }
  ```
* **Headers**:

  ```json
  {
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>"
  }
  ```
* **Body** *(form-data)*:

  ```json
  {
    "isActive": true,
    "retryCount": 5,
    "webHookUrl": "https://webhook.site/example",
    "exponentialBackoffFactor": 2.0,
    "includeImageData": true
  }
  ```

**Example Response**

```json
{
    "id": "d8382f6f-fc70-42aa-99a9-06c1948cd36a",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 0,
    "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://webhook.site/example\",\"RetryCount\":5,\"ExponentialBackoffFactor\":2.0}",
    "isActive": true,
    "includeImageData": true,
    "createdAt": "2024-07-30T20:35:26.4982017Z",
    "updatedAt": "2024-07-30T20:35:26.4982468Z"
}
```

***

> **Notes:** All API requests must include valid JWT tokens in the header, along with `x-api-key` and `x-api-secret` values.
>
> #### Enum Values in Responses
>
> In the responses, the `NotificationChannel` property represents the type of notification channel used. This property corresponds to the following enum values:

| Enum Value | Integer Representation | Description      |
| ---------- | ---------------------- | ---------------- |
| `WebHook`  | 0                      | Webhook channel  |
| `SignalR`  | 1                      | SignalR channel  |
| `RabbitMQ` | 2                      | RabbitMQ channel |

> Please use these mappings to interpret the `NotificationChannel` values in the API responses.

***


# How to Receive Notifications

### Overview

To receive notifications, you need to configure a WebHook Notification Channel for your application. Notifications such as **ImageGenerationProgress** and **ImageGenerationTaskCompleted** will be sent to the configured endpoint.

### Setting Up a WebHook Listener

Below is an example implementation of a WebHook listener to receive and parse notifications.

#### Example Listener (C#)

```csharp
/// <summary>
/// Listens to the AdCreative API webhook notifications.
/// </summary>
[HttpPost, AllowAnonymous]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status500InternalServerError)]
public async Task<IActionResult> WebhookListener()
{
    using var reader = new StreamReader(Request.Body);
    var jsonBody = await reader.ReadToEndAsync();

    if (string.IsNullOrEmpty(jsonBody))
    {
        _logger.LogError("Invalid WebHook request body.");
        return BadRequest("Invalid WebHook request body.");
    }

    var message = UnionConverter<INotificationMessage>.Deserialize(jsonBody);

    switch (message)
    {
        case ImageGenerationProgress progress:
            _logger.LogInformation("Image Generation Progress received for User: {0}", progress.UserId);
            // Process Progress
            break;

        case ImageGenerationTaskCompleted taskCompleted:
            _logger.LogInformation("Image Generation Task Completed for User: {0}", taskCompleted.UserId);
            // Process Task Completion
            break;
            
        case ImageUpscalingProgress progress:
            _logger.LogInformation("Image Upscaling Progress received for User: {0}", progress.UserId);
            // Process Progress
            break;

        case ImageUpscalingTaskCompleted taskCompleted:
            _logger.LogInformation("Image Upscaling Task Completed for User: {0}", taskCompleted.UserId);
            // Process Task Completion
            break;
            
        case ImageFaceEnhancingProgress progress:
            _logger.LogInformation("Image Face Enhancing Progress received for User: {0}", progress.UserId);
            // Process Progress
            break;

        case ImageFaceEnhancingTaskCompleted taskCompleted:
            _logger.LogInformation("Image Face Enhancing Task Completed for User: {0}", taskCompleted.UserId);
            // Process Task Completion
            break;
            
        case ImageBackgroundRemovingProgress progress:
            _logger.LogInformation("Image Background Removing Progress received for User: {0}", progress.UserId);
            // Process Progress
            break;

        case ImageBackgroundRemovingTaskCompleted taskCompleted:
            _logger.LogInformation("Image Background Removing Task Completed for User: {0}", taskCompleted.UserId);
            // Process Task Completion
            break;
            
        case ImageStockGenerationProgress progress:
            _logger.LogInformation("Image Stock Generation Progress received for User: {0}", progress.UserId);
            // Process Progress
            break;

        case ImageStockGenerationTaskCompleted taskCompleted:
            _logger.LogInformation("Image Stock Generation Task Completed for User: {0}", taskCompleted.UserId);
            // Process Task Completion
            break;

        default:
            _logger.LogWarning("Unknown notification type received.");
            return BadRequest("Unknown notification type.");
    }

    return Ok();
}
```

### Notification Message Types

#### 1. ImageGenerationTaskCompleted

Represents a notification sent when an image generation task is completed.

**Sample JSON Structure**

```json
{
    "MessageType": "ImageGenerationTaskCompleted",
    "ApplicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "UserId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "ImageRenderProcessId": "cbda4889-ac1d-4073-9b84-b3ab29417606",
    "TaskId": "9baa8e55-ddc8-4940-907f-eb5fc81e53f6",
    "ImageContentBytes": "BASE64_ENCODED_IMAGE_DATA",
    "IsSuccessful": true,
    "ErrorMessage": ""
}
```

#### 2. ImageGenerationProgress

Represents the progress of an image generation process.

**Sample JSON Structure**

```json
{
    "MessageType": "ImageGenerationProgress",
    "RequestRenderState": 1,
    "ApplicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "UserId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "ImageRenderProcessId": "cbda4889-ac1d-4073-9b84-b3ab29417606",
    "TotalTaskCount": 10,
    "CompletedTaskCount": 5,
    "Progress": 50.0,
    "Tasks": {
        "9baa8e55-ddc8-4940-907f-eb5fc81e53f6": 5
    },
    "RenderKind": 1,
    "RenderType": 2,
    "IsSuccessful": true,
    "ErrorMessage": ""
}
```

### Key Considerations

1. **Endpoint Security:**
   * ***Currently, no authentication mechanisms are supported for WebHook endpoints. Ensure your endpoint is secure.***
   * ***Future updates will include authentication support.***
2. **Message Parsing:**
   * Use a JSON parser compatible with your programming language to handle incoming messages.
   * Validate the message structure before processing.
3. **Error Handling:**
   * Return appropriate HTTP status codes (`400`, `500`) for malformed requests or server-side issues.

***

### Language-Agnostic Workflow

1. **Setup WebHook Endpoint:**
   * Create a POST endpoint to listen for incoming notifications.
2. **Read Request Body:**
   * Parse the incoming JSON payload to extract the notification message.
3. **Identify Message Type:**
   * Use the `MessageType` field to determine the notification type.
4. **Process Message:**
   * Handle each message type appropriately.

***


# Rate Limits


# Error Handling

#### Error Response Structure

The API adheres to a standardized error response format to ensure consistent communication of errors. Below is a breakdown of the fields and examples:

**Fields in Error Response:**

* **type**: A URI reference to the documentation about the type of error.
* **title**: A short, human-readable summary of the problem type.
* **status**: The HTTP status code applicable to this error.
* **traceId**: A unique identifier for the error occurrence, helpful for debugging and tracing logs.
* **errors**: A dictionary containing detailed error messages from different layers of the application.

**Explanation of the `errors` Dictionary**

The `errors` field is designed to provide granular error details across the application's layers. This dictionary includes keys that specify the layer and function where the error occurred, with corresponding error messages.

* **business**: Represents errors from the business logic layer.
* **engine**: Represents errors from the engine or lower-level operations.

**Examples**

**Example 1: Business and Engine Layer Errors**

```json
{
    "errors": {
        "engine: AdCreativesByTemplates": [
            "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f."
        ],
        "business: AdCreativesByTemplates": [
            "Not found error occurred while starting image render process."
        ]
    },
    "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-bacf1fb30e365a645a8b00cf3d4ed8f3-cd47bc0024a41426-00"
    }
}
```

This example highlights errors occurring first in the engine layer (`AdCreativesByTemplates` function) and subsequently propagated to the business layer. Each layer adds its error details to the `errors` dictionary.

**Example 2: Validation Error**

```json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-131a39782d3aa54ef0cfae62c715a4e2-61df78abdb62e43d-00",
  "errors": {
      "model": [
          "The model field is required."
      ],
      "$.applicationId": [
          "The JSON value could not be converted to System.Guid. Path: $.applicationId | LineNumber: 1 | BytePositionInLine: 56."
      ]
  }
}
```

This example demonstrates a validation error, where an invalid value for `applicationId` results in a failure.

**Example 3: Timeout Error**

```json
{
    "errors": {
        "business:": [
            "HttpClient: The request was canceled due to the configured HttpClient.Timeout of 100 seconds elapsing."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "An unexpected error occurred.",
    "status": 500,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-90ad77169df4211cd5d7fc6f18b90337-3e5cec4b638b3c38-00"
    }
}
```

This example demonstrates a timeout error in the business layer, where an HTTP request exceeded the configured timeout.

***

#### Summary

The structured error format provides transparency and actionable details for debugging and issue resolution, aiding developers in pinpointing and addressing issues efficiently.


# Enums and Descriptions

## Enum Definitions and JSON Representation

This document provides a comprehensive explanation of the enums used in the AdCreative API. These enums are essential for understanding the JSON requests and responses, enabling developers to use the correct values.

***

### 1. `RenderKind`

The `RenderKind` enum specifies the dimensions of the output renders. Each value corresponds to a specific size or group of sizes.

#### Definition

```json
{
    "Unset": 0,
    "Post": 1,
    "Story": 2,
    "Landscape": 4,
    "Vertical": 8,
    "PinSize": 16,
    "Social": 31,
    "MediumBanner": 32,
    "LeaderBoard": 64,
    "WideSkyScraper": 128,
    "HalfPage": 256,
    "LargeLeaderboard": 512,
    "FullHD": 1024,
    "Portrait": 2048,
    "Widescreen": 4096,
    "VideoPortrait": 8192,
    "VideoLandscape": 16384,
    "Display": 992,
    "All": 1023
}
```

#### Description

<table><thead><tr><th width="217">Value</th><th width="316">Description</th><th>Dimensions</th></tr></thead><tbody><tr><td><code>Unset</code></td><td>No rendering type set.</td><td>N/A</td></tr><tr><td><code>Post</code></td><td>Square post size.</td><td>1080x1080 px</td></tr><tr><td><code>Story</code></td><td>Vertical story size.</td><td>1080x1920 px</td></tr><tr><td><code>Landscape</code></td><td>Landscape size for banners.</td><td>1200x628 px</td></tr><tr><td><code>Vertical</code></td><td>Vertical size for portrait ads.</td><td>1080x1350 px</td></tr><tr><td><code>PinSize</code></td><td>Pinterest-specific size.</td><td>1000x1500 px</td></tr><tr><td><code>Social</code></td><td>Combination of all social sizes.</td><td>Multiple sizes</td></tr><tr><td><code>MediumBanner</code></td><td>Medium rectangle banner.</td><td>300x250 px</td></tr><tr><td><code>LeaderBoard</code></td><td>Large horizontal banner.</td><td>728x90 px</td></tr><tr><td><code>WideSkyScraper</code></td><td>Tall vertical banner.</td><td>160x600 px</td></tr><tr><td><code>HalfPage</code></td><td>Large vertical half-page banner.</td><td>300x600 px</td></tr><tr><td><code>LargeLeaderboard</code></td><td>Large leaderboard banner.</td><td>970x90 px</td></tr><tr><td><code>FullHD</code></td><td>Full HD resolution.</td><td>1920x1080 px</td></tr><tr><td><code>Portrait</code></td><td>Portrait resolution.</td><td>768x1024 px</td></tr><tr><td><code>Widescreen</code></td><td>Widescreen resolution.</td><td>1024x768 px</td></tr><tr><td><code>VideoPortrait</code></td><td>Portrait-oriented video resolution.</td><td>768x1280 px</td></tr><tr><td><code>VideoLandscape</code></td><td>Landscape-oriented video resolution.</td><td>1280x768 px</td></tr><tr><td><code>Display</code></td><td>Combination of display ad sizes.</td><td>Multiple sizes</td></tr><tr><td><code>All</code></td><td>All possible sizes.</td><td>Multiple sizes</td></tr></tbody></table>

***

### 2. `RenderType`

The `RenderType` enum specifies the type of output render.

#### Definition

```json
{
    "Unset": 0,
    "Html": 1,
    "Svg": 2,
    "AiProduct": 4,
    "AiImageUpscaling": 8,
    "AiProductCreative": 16,
    "AiImageGeneration": 32,
    "AiSampledImageGeneration": 64,
    "AiFaceEnhancing": 128,
    "AiInPainting": 1024,
    "AiOutPainting": 127,
    "AiDressing": 256,
    "AiDetailEnhancing": 512,
    "TemplateBased": 19,
    "AiGenerationBased": 100,
    "All": 127
}
```

#### Description

| Value                      | Description                                 |
| -------------------------- | ------------------------------------------- |
| `Unset`                    | No render type set.                         |
| `Html`                     | HTML-based render (deprecated).             |
| `Svg`                      | SVG format render.                          |
| `AiProduct`                | AI-generated product images.                |
| `AiImageUpscaling`         | AI-based image upscaling.                   |
| `AiProductCreative`        | AI-generated product creatives.             |
| `AiImageGeneration`        | AI-based image generation.                  |
| `AiSampledImageGeneration` | AI image generation using a sample.         |
| `AiFaceEnhancing`          | AI-based facial detail enhancement.         |
| `AiInPainting`             | AI-based in-painting for image restoration. |
| `AiOutPainting`            | AI-based out-painting for extending images. |
| `AiDressing`               | AI dressing of models.                      |
| `AiDetailEnhancing`        | AI-based detail enhancement.                |
| `TemplateBased`            | Template-based rendering types.             |
| `AiGenerationBased`        | AI generation-related rendering types.      |
| `All`                      | All rendering types.                        |

***

### 3. `RenderState`

The `RenderState` enum describes the state of a rendering process.

#### Definition

```json
{
    "NotStarted": 0,
    "Started": 1,
    "Scheduled": 2,
    "Cancelled": 3,
    "Failed": 4,
    "Succeeded": 5,
    "Default": 0
}
```

#### Description

| Value        | Description                                     |
| ------------ | ----------------------------------------------- |
| `NotStarted` | The render process has not started.             |
| `Started`    | The render process has started.                 |
| `Scheduled`  | The render process is scheduled.                |
| `Cancelled`  | The render process was cancelled.               |
| `Failed`     | The render process failed.                      |
| `Succeeded`  | The render process succeeded.                   |
| `Default`    | The default state (equivalent to `NotStarted`). |

***

### 4. `NotificationChannel`

The `NotificationChannel` enum specifies the channel for notifications.

#### Definition

```json
{
    "WebHook": 0,
    "SignalR": 1,
    "RabbitMQ": 2
}
```

#### Description

| Value      | Description                          |
| ---------- | ------------------------------------ |
| `WebHook`  | Notifications are sent via WebHook.  |
| `SignalR`  | Notifications are sent via SignalR.  |
| `RabbitMQ` | Notifications are sent via RabbitMQ. |

***

### 5. `ImageStyle`

The `ImageStyle` enum specifies various styles for generating stock images. Each value represents a unique style, providing users with diverse options for image creation. Below is the detailed documentation for each enum value, including its purpose and description.

***

### Definition

```json
{
    "Unset": 0,
    "CustomWithText": 1,
    "CustomWithImage": 2,
    "Photorealistic": 3,
    "StudioShot": 4,
    "ThreeDRender": 5,
    "HighlyDetailed": 6,
    "Fantasy": 7,
    "Cinematic": 8,
    "Cyberpunk": 9,
    "DigitalPainting": 10,
    "IsometricArt": 11,
    "Surrealism": 12
}
```

***

### Enum Values

<table><thead><tr><th width="234">Name</th><th width="85">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>Unset</code></td><td>0</td><td>The image style is unset. This is the default value.</td></tr><tr><td><code>CustomWithText</code></td><td>1</td><td>Custom image style with added text elements.</td></tr><tr><td><code>CustomWithImage</code></td><td>2</td><td>The style is derived from a custom image provided by the user.</td></tr><tr><td><code>Photorealistic</code></td><td>3</td><td>Stock images with lifelike precision and detail.</td></tr><tr><td><code>StudioShot</code></td><td>4</td><td>Clean, focused images with soft, professional lighting.</td></tr><tr><td><code>ThreeDRender</code></td><td>5</td><td>3D-rendered images with realistic depth and polished textures.</td></tr><tr><td><code>HighlyDetailed</code></td><td>6</td><td>Highly detailed images with intricate textures and sharp definition.</td></tr><tr><td><code>Fantasy</code></td><td>7</td><td>Mystical and enchanting visuals with a touch of magic.</td></tr><tr><td><code>Cinematic</code></td><td>8</td><td>Dramatic lighting and intense shadows for a filmic look.</td></tr><tr><td><code>Cyberpunk</code></td><td>9</td><td>Futuristic style with neon highlights and high-tech aesthetics.</td></tr><tr><td><code>DigitalPainting</code></td><td>10</td><td>Artistically crafted visuals with bold colors and soft strokes.</td></tr><tr><td><code>IsometricArt</code></td><td>11</td><td>Precise, structured visuals with a three-dimensional perspective.</td></tr><tr><td><code>Surrealism</code></td><td>12</td><td>Dreamlike scenes with abstract, otherworldly elements.</td></tr></tbody></table>

***

### Usage Examples

#### Example 1: Setting Image Style

```csharp
var imageStyle = ImageStyle.Photorealistic;
Console.WriteLine($"Selected image style: {imageStyle}");
```

#### Example 2: Conditional Logic with Image Styles

```csharp
switch (imageStyle)
{
    case ImageStyle.Cyberpunk:
        Console.WriteLine("Creating a futuristic cyberpunk-themed image...");
        break;
    case ImageStyle.Fantasy:
        Console.WriteLine("Generating a magical fantasy-themed image...");
        break;
    default:
        Console.WriteLine("Using default image style.");
        break;
}
```

***

### Additional Notes

* The `Unset` value serves as a placeholder and should be avoided in production scenarios.
* `CustomWithText` and `CustomWithImage` allow user-provided inputs to influence the image style.
* Styles like `Photorealistic` and `StudioShot` are ideal for realistic and professional visuals, while `Fantasy` and `Cyberpunk` cater to creative and futuristic designs.

### 6. `AdTextType`

The `AdTextType` enum specifies various ad text styles and methodologies used for generating high-conversion ad copy. Each value corresponds to a specific ad text framework or principle, providing detailed examples and explanations.

### Definition

```json
{
    "Unknown": 0,
    "SharpTechnique": 1,
    "GateFramework": 2,
    "LiftMethod": 3,
    "PasFormula": 4,
    "BabFormula": 5,
    "FabFormula": 6,
    "AidaModel": 7,
    "FourCSPrinciple": 8,
    "FourUSPrinciple": 9,
    "SlapMethod": 10,
    "QuestMethod": 11,
    "AccaModel": 12,
    "KissPrinciple": 13,
    "MetaPackage": 14,
    "GooglePackage": 15,
    "OAthFormula": 16,
    "PPPPFormula": 17,
    "PaisFormula": 18,
    "AppFormula": 19,
    "SuccessMethod": 20,
    "Headline": 21,
    "ShortHeadline": 22,
    "LongHeadline": 23,
    "GoogleResponsiveSearchAds": 24,
    "GoogleResponsiveDisplayAds": 25,
    "LinkedInSingleImageVideoAds": 26,
    "LinkedInTextAds": 27,
    "BingSearchAds": 28,
    "BingDisplayAds": 29,
    "PowerPack": 30,
    "Description": 31,
    "AiRenderProductVideoFromImageChat": 32,
    "AiProductImageAndVideoRecommendationChat": 33,
    "AiProductVideoPromptRecommendationsChat": 34,
    "AiProductVideoPromptOptimizerChat": 35,
    "ProductPhotoShootImageDescription": 36,
    "ProductPhotoShootRecommendationForVideo": 37,
    "ProductPhotoShootOptimizerForVideo": 38,
    "BuyerPersona": 39
}
```

***

## AdTextType Enum Description Table

<table data-full-width="true"><thead><tr><th width="280">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>Unknown</code></td><td>Unknown text type.</td></tr><tr><td><code>SharpTechnique</code></td><td><p><strong>SHARP Technique: Short Headlines for Ads.</strong><br>Examples:</p><ul><li>Improve your child’s grades with Learning Room!</li><li>Get ahead of the competition with Learning Room!</li><li>Give your child the tools they need to succeed with Learning Room!</li><li>Help your child reach their full potential with Learning Room!</li></ul></td></tr><tr><td><code>GateFramework</code></td><td><strong>GATE Framework: General Ad Texts.</strong><br>Examples: <strong>Are you ready for a whiter, healthier smile in as little as 9 minutes per day? Our Snow Teeth Whitening Kit helps brighten teeth, remove coffee and wine stains, and doesn’t cause pain. With more than 600,000 customers who are extremely satisfied with the results, we’re sure you’ll love our at home teeth whitening kit too.</strong> Buy your kit today for immediate results!</td></tr><tr><td><code>LiftMethod</code></td><td><strong>LIFT Method: Listicle Style Ad Texts.</strong><br>Examples: <strong>At-Home Teeth Whitening Made Easy</strong><br><strong>Ad: We turn yellow and stained teeth into pearly whites in just 9-minutes a day.</strong><br><strong>😁 The World’s #1 Teeth Whitening System</strong><br><strong>⭐️ Loved by 600,000+ Happy Customers</strong><br><strong>✅ Featured in GQ, Elle, Vogue &#x26; Forbes</strong><br><strong>Get your Snow Teeth Whitening Kit today, receive 50% discount!</strong></td></tr><tr><td><code>PasFormula</code></td><td><strong>PAS Formula: Pain-Agitate-Solution Style Ad Texts.</strong><br>Pain: While you should get your teeth professionally cleaned twice a year, it’s not exactly realistic when you’re busy with work and personal commitments. Agitate: Our whitening kit removes 99% of stains within 14 days — without the pain. Solution: Whiten your teeth in minutes per day with our DIY teeth whitener solution designed for sensitive teeth and gums.</td></tr><tr><td><code>BabFormula</code></td><td><strong>BAB Formula: Before-After-Bridge Style Ad Texts.</strong><br>Examples: Before: Writing blog posts and landing pages for your clients can be a tedious task. After: ContentBot, an AI-powered copywriting assistant makes it easy. Bridge: Automate your marketing efforts and save time!</td></tr><tr><td><code>FabFormula</code></td><td><strong>FAB Formula: Feature-Advantage-Benefit Style Ad Texts.</strong><br>Features: Specially designed for making froth milk and delicious coffee. Advantages: Simple one-touch operation. Benefits: Enjoy delicious coffee with family and friends.</td></tr><tr><td><code>AidaModel</code></td><td><strong>AIDA Model: Attention, Interest, Desire, Action.</strong><br>Examples: Attention: Get a Dazzling Smile in Just 7 Days! Interest: Tired of hiding your yellow teeth? Desire: Advanced whitening technology removes stains. Action: Order now for a confident smile!</td></tr><tr><td><code>FourCSPrinciple</code></td><td><strong>4C’s Principle: Clear, Concise, Compelling, Credible.</strong><br>Examples: Clear: Whiten your teeth up to 8 shades in just 7 days. Concise: Try our enamel-safe tooth whitening gel. Compelling: Join thousands of radiant smiles! Credible: Trusted by leading dentists.</td></tr><tr><td><code>FourUSPrinciple</code></td><td><strong>4U’s Principle: Urgent, Unique, Ultra-specific, Useful.</strong><br>Examples: Urgent: Limited-time offer: Save 25%! Unique: Exclusive, patented whitening formula. Ultra-specific: Dentist-approved, results in just 7 days. Useful: Enjoy a whiter smile without hassle.</td></tr><tr><td><code>SlapMethod</code></td><td><strong>SLAP Method: Stop, Look, Act, Purchase.</strong><br>Examples: Stop: New Breakthrough: Dazzling Smiles in 7 Days! Look: Discover SmileBright, the revolutionary tooth whitening solution. Act: Ready to embrace a brilliant smile? Order now! Purchase: Buy one, get one 50% off!</td></tr><tr><td><code>QuestMethod</code></td><td><strong>QUEST Method: Qualify, Understand, Educate, Stimulate, Transition.</strong><br>Examples: Qualify: Looking for a fast way to brighten your smile? Understand: Self-conscious about yellow teeth? Educate: SmileBright delivers visible results in just 7 days. Stimulate: Imagine the confidence of a radiant smile. Transition: Order SmileBright today!</td></tr><tr><td><code>AccaModel</code></td><td><strong>ACCA Model: Awareness, Comprehension, Conviction, Action.</strong><br>Examples: Awareness: Introducing SmileBright. Comprehension: Dentist-approved formula removes stains. Conviction: Trusted by thousands for brilliant smiles. Action: Order SmileBright now!</td></tr><tr><td><code>KissPrinciple</code></td><td><strong>KISS Principle: Keep It Simple and Straightforward.</strong><br>Examples: Simple: Whiten your teeth quickly. Straightforward: Removes stubborn stains in 7 days. Call to Action: Order SmileBright today!</td></tr><tr><td><code>MetaPackage</code></td><td><strong>Meta Package: Dynamic Creative Ads.</strong><br>Examples: Meta Dynamic Creative Ads require 5 Primary Texts and 5 Headlines. Generates multiple sets using proven copywriting frameworks.</td></tr><tr><td><code>GooglePackage</code></td><td><strong>Google Package: Performance Max Ads.</strong><br>Examples: Requires 5 Headlines, 5 Long Headlines, and 5 Descriptions. Generated with high-conversion-rate methodologies.</td></tr><tr><td><code>OAthFormula</code></td><td><strong>OATH Formula: Old-Annoyed-Thorough-Hesitant Style Ad Texts.</strong><br>Examples: Self-conscious about stained teeth? Frustrated that brushing doesn’t work? Our revolutionary whitening product ensures visibly whiter teeth in just 2 weeks!</td></tr><tr><td><code>PPPPFormula</code></td><td><strong>PPPP Formula: Picture-Promise-Prove-Push Style Ad Texts.</strong><br>Examples: Picture yourself with a radiant smile. Promise: Remove years of stains. Prove: Testimonials and before-and-after photos. Push: Start smiling with confidence!</td></tr><tr><td><code>PaisFormula</code></td><td><strong>PAIS Formula: Problem-Agitate-Invalidate-Solve Style Ad Texts.</strong><br>Examples: Problem: Struggling with teeth stains? Agitate: Lack of potency in over-the-counter solutions. Invalidate: Whitening toothpaste isn’t enough. Solve: Our product guarantees results in just 2 weeks.</td></tr><tr><td><code>AppFormula</code></td><td><strong>APP Formula: Agree-Promise-Preview Style Ad Texts.</strong><br>Examples: Agree: A bright smile boosts confidence. Promise: Removes deep-set stains. Preview: Efficient and easy-to-use whitening solution.</td></tr><tr><td><code>SuccessMethod</code></td><td><strong>SUCCESs Method: Simple-Unexpected-Concrete-Credible-Emotional-Story Style Ad Texts.</strong><br>Examples: Simple: Whiten your teeth easily. Unexpected: Immediate visible effects. Credible: Trusted by dentists. Emotional: Joy of transformation. Story: A brighter smile starts here.</td></tr><tr><td><code>Headline</code></td><td>Headline text type.</td></tr><tr><td><code>ShortHeadline</code></td><td>Short Headline text type.</td></tr><tr><td><code>LongHeadline</code></td><td>Long Headline text type.</td></tr><tr><td><p><code>GoogleResponsive</code></p><p><code>SearchAds</code></p></td><td><strong>Google Package: Responsive Search Ads.</strong><br>Examples: 15 Headlines (30 characters) and 4 Descriptions (90 characters) required. High conversion rates achieved through tested methodologies.</td></tr><tr><td><p><code>GoogleResponsive</code></p><p><code>DisplayAds</code></p></td><td><strong>Google Package: Responsive Display Ads.</strong><br>Examples: 5 Headlines (30 characters), 1 Long Headline (90 characters), and 5 Descriptions (90 characters). Consistently high conversion rates.</td></tr><tr><td><p><code>LinkedInSingle</code></p><p><code>ImageVideoAds</code></p></td><td><strong>LinkedIn Package: Single Image/Video Ads.</strong><br>Examples: Requires 1 headline (up to 100 characters) and 1 description (up to 600 characters). More than 10 texts generated.</td></tr><tr><td><code>LinkedInTextAds</code></td><td><strong>LinkedIn Package: Text Ads.</strong><br>Examples: Requires 1 headline (up to 25 characters) and 1 description (up to 75 characters). Generates over 10 options.</td></tr><tr><td><code>BingSearchAds</code></td><td><strong>Bing Ads Package: Search Ads.</strong><br>Examples: 15 Headlines (30 characters) and 4 Descriptions (90 characters) required. Optimized for high conversion rates.</td></tr><tr><td><code>BingDisplayAds</code></td><td><strong>Bing Ads Package: Audience Display Ads.</strong><br>Examples: Requires 15 Short Headlines, 5 Long Headlines, and 5 Ad Texts.</td></tr><tr><td><code>PowerPack</code></td><td><strong>Power Pack: All-in-one Ad Text Package.</strong><br>Examples: Generates over 20 conversion-focused ad texts using all powerful copywriting techniques at AdCreative.ai.</td></tr><tr><td><code>Description</code></td><td>Description text type.</td></tr><tr><td><p><code>AiRenderProduct</code></p><p><code>VideoFromImageChat</code></p></td><td>AI Render Product Video From Image Chat text type.</td></tr><tr><td><p><code>AiProductImageAndVideo</code></p><p><code>RecommendationChat</code></p></td><td>AI Product Image And Video Recommendation Chat text type.</td></tr><tr><td><p><code>AiProductVideoPrompt</code></p><p><code>RecommendationsChat</code></p></td><td>AI Product Video Prompt Recommendations Chat text type.</td></tr><tr><td><p><code>AiProductVideoPrompt</code></p><p><code>OptimizerChat</code></p></td><td>AI Product Video Prompt Optimizer Chat text type.</td></tr><tr><td><p><code>ProductPhotoShootImage</code></p><p><code>Description</code></p></td><td>Product Photo Shoot Image Description text type.</td></tr><tr><td><p><code>ProductPhotoShoot</code></p><p><code>RecommendationForVideo</code></p></td><td>Product Photo Shoot Recommendation For Video text type.</td></tr><tr><td><p><code>ProductPhotoShoot</code></p><p><code>OptimizerForVideo</code></p></td><td>Product Photo Shoot Optimizer For Video text type.</td></tr><tr><td><code>BuyerPersona</code></td><td>Buyer Persona text type.</td></tr></tbody></table>

***

### 6. `AdTextTones`

#### AdTextTones Enum - JSON Format and Usage Guide

The **AdTextTones** enum represents the tone of the generated text output in the API. Each tone is provided as a descriptive string value to ensure clarity and ease of use. Below is the JSON representation of the enum, followed by an explanation for implementing it in your API requests.

***

**JSON Representation**

```json
{
  "AdTextTones": [
    "Professional",
    "Informal",
    "Friendly",
    "Enthusiastic",
    "Humorous",
    "Inspirational",
    "Persuasive",
    "Luxurious",
    "Conversational",
    "Educational",
    "Emotional",
    "Authoritative",
    "Nostalgic",
    "Romantic",
    "Playful",
    "Sarcastic",
    "Urgent",
    "Empathetic",
    "Uplifting",
    "Minimalist"
  ]
}
```

***

**Explanation**

* **Purpose:**\
  The `AdTextTones` enum defines the tone of the text content generated by the API. Developers can choose the desired tone by passing its string value (e.g., `"Friendly"`, `"Professional"`) in the relevant API request.
* **Data Type:**\
  The tone values are provided as strings to ensure compatibility and readability in API integrations.
* **Example Use Case:**\
  When creating a text generation request, the tone can be specified in the payload to align the generated content with the desired communication style.

***

**Example Request Payload**

Below is an example of how to include a tone selection in your API request:

```json
{
  "projectName": "Marketing Campaign 2025",
  "contentType": "Ad Copy",
  "tone": "Inspirational",
  "keywords": ["innovative", "sustainable", "future-focused"],
  "targetAudience": "Tech Enthusiasts"
}
```

* **Field Descriptions:**
  * `projectName`: The name of the project for reference.
  * `contentType`: The type of content you are generating.
  * `tone`: The selected tone for the text generation, chosen from the `AdTextTones` enum.
  * `keywords`: Keywords to focus on in the generated text.
  * `targetAudience`: The audience the text is aimed at.

***

**Notes**

* Ensure that the `tone` field in your API payload contains one of the valid values from the `AdTextTones` enum.
* If no tone is specified, the API may default to a neutral tone (e.g., `"Professional"`).

This structured approach allows developers to produce content that matches the desired tone and ensures consistent integration with the API.

## AdTextTones Enum Description Table

<table><thead><tr><th width="209">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>Professional</code></td><td>Uses a formal and polished tone suitable for business or official communications.</td></tr><tr><td><code>Informal</code></td><td>A casual tone that feels relaxed and conversational.</td></tr><tr><td><code>Friendly</code></td><td>A warm and welcoming tone that makes the reader feel comfortable and appreciated.</td></tr><tr><td><code>Enthusiastic</code></td><td>A highly energetic tone that conveys excitement and eagerness.</td></tr><tr><td><code>Humorous</code></td><td>A light-hearted tone that incorporates humor to engage the audience.</td></tr><tr><td><code>Inspirational</code></td><td>A motivating tone that encourages and uplifts the audience.</td></tr><tr><td><code>Persuasive</code></td><td>A compelling tone designed to influence and convince the audience.</td></tr><tr><td><code>Luxurious</code></td><td>A tone that conveys elegance, opulence, and high-quality experiences.</td></tr><tr><td><code>Conversational</code></td><td>A natural and interactive tone that mimics real-life conversations.</td></tr><tr><td><code>Educational</code></td><td>An informative tone that simplifies concepts for learning and understanding.</td></tr><tr><td><code>Emotional</code></td><td>A tone that evokes strong feelings and connects with the reader on a deeper level.</td></tr><tr><td><code>Authoritative</code></td><td>A confident and assertive tone that establishes trust and credibility.</td></tr><tr><td><code>Nostalgic</code></td><td>A tone that evokes memories of the past and creates a sense of longing.</td></tr><tr><td><code>Romantic</code></td><td>A tone filled with affection, passion, and emotional connection.</td></tr><tr><td><code>Playful</code></td><td>A tone that is fun, light, and full of joy, often using creative language.</td></tr><tr><td><code>Sarcastic</code></td><td>A witty and ironic tone used to make a point in a humorous or cutting way.</td></tr><tr><td><code>Urgent</code></td><td>A tone that creates a sense of immediacy and importance, prompting quick action.</td></tr><tr><td><code>Empathetic</code></td><td>A tone that shows understanding and care, connecting with the reader’s emotions.</td></tr><tr><td><code>Uplifting</code></td><td>A positive and encouraging tone designed to boost morale and inspire hope.</td></tr><tr><td><code>Minimalist</code></td><td>A tone that is simple, clear, and concise, focusing only on essential details.</td></tr></tbody></table>

***

### 7. `AdTextEmojiSelection`

## AdTextEmojiSelection Enum Documentation

### Overview

The `AdTextEmojiSelection` enum is used to define the emoji preference for AI-generated ad texts. This enum is represented by integers when sent as parameters in API requests.

### Enum Definition

```csharp
namespace AdCreative.AdGenius.API.Enums.AdTextGeneration;

/// <summary>
/// The ad text emoji selection for AI.
/// </summary>
public enum AdTextEmojiSelection
{
    /// <summary>
    /// Text with emojis.
    /// </summary>
    WithEmojis,

    /// <summary>
    /// Text without emojis.
    /// </summary>
    WithoutEmojis,

    /// <summary>
    /// Text chosen by AI.
    /// </summary>
    ChosenByAi,
}
```

### JSON Representation

### Definition

```json
{
  "AdTextEmojiSelection": [
    "WithEmojis": 0,
    "WithoutEmojis": 1,
    "ChosenByAi": 2,
  ]
}
```

When using this enum in an API request, it is represented as integers:

```json
{
  "emojiPreference": 0 // Example: With Emojis
}
```

### Enum Values and Descriptions

<table><thead><tr><th width="129">Value</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>0</code></td><td>WithEmojis</td><td>Text with emojis.</td></tr><tr><td><code>1</code></td><td>WithoutEmojis</td><td>Text without emojis.</td></tr><tr><td><code>2</code></td><td>ChosenByAi</td><td>Text preference chosen by the AI.</td></tr></tbody></table>

***

### Example Usage

#### C# Example

```csharp
var selection = AdTextEmojiSelection.ChosenByAi;
Console.WriteLine((int)selection); // Outputs: 2
```

#### API Request Example

Using Postman or any HTTP client:

**Request Body**

```json
{
  "emojiSelection": 1
}
```

**Explanation**

* `emojiPreference`: Specifies whether the generated text should include emojis (`0`), exclude emojis (`1`), or let the AI decide (`2`).

***

### Notes

* Ensure the value sent matches the defined range (`0`, `1`, or `2`).
* The default behavior should be explicitly defined in your application logic if no value is provided.

This document serves as a reference for all enum definitions, ensuring consistent and correct usage in JSON requests and responses.

***


# Notification Message Types

## Notification Message Types Documentation

This document describes the two primary notification message types (`ImageGenerationTaskCompleted` and `ImageGenerationProgress`) used in the AdCreative system. These messages can be consumed via **WebHook HTTP endpoints** or **RabbitMQ queues**.

### Overview of Notification Delivery Mechanisms

1. **WebHook HTTP Endpoint**:\
   Messages are sent as HTTP POST requests to a specified endpoint. The message payload is serialized in JSON format.
2. **RabbitMQ Queue**:\
   Messages are delivered to the specified RabbitMQ queue in a serialized binary or JSON format.

***

### Notification Message Types

#### Common Structure

All notification message types share the same structure, with the only difference being the `MessageType` field.

#### List of Message Types

* `ImageGenerationProgress`
* `ImageUpscalingProgress`
* `ImageFaceEnhancingProgress`
* `ImageBackgroundRemovingProgress`
* `ImageStockGenerationProgress`
* `ImageGenerationTaskCompleted`
* `ImageUpscalingTaskCompleted`
* `ImageFaceEnhancingTaskCompleted`
* `ImageBackgroundRemovingTaskCompleted`
* `ImageStockGenerationTaskCompleted`

The `MessageType` field specifies the type of notification being sent.

***

#### 1. **ImageGenerationTaskCompleted**

**Description:**

This message is sent when a single image generation task is completed, indicating whether the task was successful and including the image content if applicable.

**WebHook JSON Example**

```json
{
  "MessageType": "ImageGenerationTaskCompleted",
  "ApplicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
  "UserId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "ImageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f",
  "TaskId": "9baa8e55-ddc8-4940-907f-eb5fc81e53f6",
  "ImageContentBytes": "base64encodedimagecontent==",
  "IsSuccessful": true,
  "ErrorMessage": ""
}
```

**RabbitMQ Model**

* **Exchange**: `image-render.notifications`
* **Routing Key**: `task.completed`
* **Message Payload**:

  ```json
  {
    "MessageType": "ImageGenerationTaskCompleted",
    "ApplicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "UserId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "ImageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f",
    "TaskId": "9baa8e55-ddc8-4940-907f-eb5fc81e53f6",
    "ImageContentBytes": "base64encodedimagecontent==",
    "IsSuccessful": true,
    "ErrorMessage": ""
  }
  ```

***

#### 2. **ImageGenerationProgress**

**Description:**

This message provides the current progress of an image generation process, detailing task completion status and other metadata.

**WebHook JSON Example**

```json
{
  "MessageType": "ImageGenerationProgress",
  "RequestRenderState": "Succeeded",
  "ApplicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
  "UserId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "ImageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f",
  "TotalTaskCount": 10,
  "CompletedTaskCount": 8,
  "Progress": 80.0,
  "Tasks": {
    "24929cc8-34da-455b-a4f1-61f895ac3a06": "Succeeded",
    "855c3f61-0f00-457a-81a0-b2c0653d2b21": "Succeeded"
  },
  "RenderKind": 1,
  "RenderType": 2,
  "IsSuccessful": true,
  "ErrorMessage": ""
}
```

**RabbitMQ Model**

* **Exchange**: `image-render.notifications`
* **Routing Key**: `progress.update`
* **Message Payload**:

  ```json
  {
    "MessageType": "ImageGenerationProgress",
    "RequestRenderState": "Started",
    "ApplicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "UserId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "ImageRenderProcessId": "51d690da-f5ea-405e-90ff-10d56b0d633f",
    "TotalTaskCount": 10,
    "CompletedTaskCount": 3,
    "Progress": 30.0,
    "Tasks": {
      "24929cc8-34da-455b-a4f1-61f895ac3a06": "Started",
      "855c3f61-0f00-457a-81a0-b2c0653d2b21": "NotStarted"
    },
    "RenderKind": 1,
    "RenderType": 2,
    "IsSuccessful": true,
    "ErrorMessage": ""
  }
  ```

***

### How to Consume Notifications

#### WebHook Endpoint

1. **Setup**:
   * Provide the WebHook URL during application configuration.
   * Ensure the endpoint accepts HTTP POST requests with JSON payloads.
2. **Processing**:
   * Parse the `MessageType` field to determine the type of notification.
   * Handle the notification data as required.

#### RabbitMQ Queue

1. **Setup**:
   * Bind to the exchange `image-render.notifications` with appropriate routing keys (`task.completed`, `progress.update`).
   * Consume messages from the queue.
2. **Processing**:
   * Deserialize the message payload into the appropriate model (`ImageGenerationTaskCompleted` or `ImageGenerationProgress`).
   * Implement business logic based on the notification type and content.

***

### Notes

* **Security**:
  * Ensure RabbitMQ queues are securely configured with proper access credentials.
  * Validate incoming WebHook requests to verify authenticity.
* **Retry Mechanisms**:
  * Implement retry logic for failed WebHook delivery attempts.
  * Handle RabbitMQ message requeuing for unprocessed messages.

This documentation should help developers understand and integrate notification message types effectively into their systems.


# Publish your docs

Once you’ve finished writing, editing, or importing your content, you can publish your work to the web as a docs site. Once published, your site will be accessible online only to your selected audience.

You can publish your site and find related settings from your docs site's homepage.

<figure><img src="https://gitbookio.github.io/onboarding-template-images/publish-hero.png" alt=""><figcaption></figcaption></figure>


# Common Resources

## Enum Definitions and JSON Representation

This document provides a comprehensive explanation of the enums used in the AdCreative API. These enums are essential for understanding the JSON requests and responses, enabling developers to use the correct values.

***

### 1. `RenderKind`

The `RenderKind` enum specifies the dimensions of the output renders. Each value corresponds to a specific size or group of sizes.

#### Definition

```json
{
    "Unset": 0,
    "Post": 1,
    "Story": 2,
    "Landscape": 4,
    "Vertical": 8,
    "PinSize": 16,
    "Social": 31,
    "MediumBanner": 32,
    "LeaderBoard": 64,
    "WideSkyScraper": 128,
    "HalfPage": 256,
    "LargeLeaderboard": 512,
    "FullHD": 1024,
    "Portrait": 2048,
    "Widescreen": 4096,
    "VideoPortrait": 8192,
    "VideoLandscape": 16384,
    "Display": 992,
    "All": 1023
}
```

#### Description

| Value              | Description                          | Dimensions     |
| ------------------ | ------------------------------------ | -------------- |
| `Unset`            | No rendering type set.               | N/A            |
| `Post`             | Square post size.                    | 1080x1080 px   |
| `Story`            | Vertical story size.                 | 1080x1920 px   |
| `Landscape`        | Landscape size for banners.          | 1200x628 px    |
| `Vertical`         | Vertical size for portrait ads.      | 1080x1350 px   |
| `PinSize`          | Pinterest-specific size.             | 1000x1500 px   |
| `Social`           | Combination of all social sizes.     | Multiple sizes |
| `MediumBanner`     | Medium rectangle banner.             | 300x250 px     |
| `LeaderBoard`      | Large horizontal banner.             | 728x90 px      |
| `WideSkyScraper`   | Tall vertical banner.                | 160x600 px     |
| `HalfPage`         | Large vertical half-page banner.     | 300x600 px     |
| `LargeLeaderboard` | Large leaderboard banner.            | 970x90 px      |
| `FullHD`           | Full HD resolution.                  | 1920x1080 px   |
| `Portrait`         | Portrait resolution.                 | 768x1024 px    |
| `Widescreen`       | Widescreen resolution.               | 1024x768 px    |
| `VideoPortrait`    | Portrait-oriented video resolution.  | 768x1280 px    |
| `VideoLandscape`   | Landscape-oriented video resolution. | 1280x768 px    |
| `Display`          | Combination of display ad sizes.     | Multiple sizes |
| `All`              | All possible sizes.                  | Multiple sizes |

***

### 2. `RenderType`

The `RenderType` enum specifies the type of output render.

#### Definition

```json
{
    "Unset": 0,
    "Html": 1,
    "Svg": 2,
    "AiProduct": 4,
    "AiImageUpscaling": 8,
    "AiProductCreative": 16,
    "AiImageGeneration": 32,
    "AiSampledImageGeneration": 64,
    "AiFaceEnhancing": 128,
    "AiInPainting": 1024,
    "AiOutPainting": 127,
    "AiDressing": 256,
    "AiDetailEnhancing": 512,
    "TemplateBased": 19,
    "AiGenerationBased": 100,
    "All": 127
}
```

#### Description

| Value                      | Description                                 |
| -------------------------- | ------------------------------------------- |
| `Unset`                    | No render type set.                         |
| `Html`                     | HTML-based render (deprecated).             |
| `Svg`                      | SVG format render.                          |
| `AiProduct`                | AI-generated product images.                |
| `AiImageUpscaling`         | AI-based image upscaling.                   |
| `AiProductCreative`        | AI-generated product creatives.             |
| `AiImageGeneration`        | AI-based image generation.                  |
| `AiSampledImageGeneration` | AI image generation using a sample.         |
| `AiFaceEnhancing`          | AI-based facial detail enhancement.         |
| `AiInPainting`             | AI-based in-painting for image restoration. |
| `AiOutPainting`            | AI-based out-painting for extending images. |
| `AiDressing`               | AI dressing of models.                      |
| `AiDetailEnhancing`        | AI-based detail enhancement.                |
| `TemplateBased`            | Template-based rendering types.             |
| `AiGenerationBased`        | AI generation-related rendering types.      |
| `All`                      | All rendering types.                        |

***

### 3. `RenderState`

The `RenderState` enum describes the state of a rendering process.

#### Definition

```json
{
    "NotStarted": 0,
    "Started": 1,
    "Scheduled": 2,
    "Cancelled": 3,
    "Failed": 4,
    "Succeeded": 5,
    "Default": 0
}
```

#### Description

| Value        | Description                                     |
| ------------ | ----------------------------------------------- |
| `NotStarted` | The render process has not started.             |
| `Started`    | The render process has started.                 |
| `Scheduled`  | The render process is scheduled.                |
| `Cancelled`  | The render process was cancelled.               |
| `Failed`     | The render process failed.                      |
| `Succeeded`  | The render process succeeded.                   |
| `Default`    | The default state (equivalent to `NotStarted`). |

***

### 4. `NotificationChannel`

The `NotificationChannel` enum specifies the channel for notifications.

#### Definition

```json
{
    "WebHook": 0,
    "SignalR": 1,
    "RabbitMQ": 2
}
```

#### Description

| Value      | Description                          |
| ---------- | ------------------------------------ |
| `WebHook`  | Notifications are sent via WebHook.  |
| `SignalR`  | Notifications are sent via SignalR.  |
| `RabbitMQ` | Notifications are sent via RabbitMQ. |

***

This document serves as a reference for all enum definitions, ensuring consistent and correct usage in JSON requests and responses.

***


# Support


# AdCreative API

<figure><img src="https://1994826232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwTYepDyTMpGFxRZfslZA%2Fuploads%2FGTzC7qs1RjXj5sx8EFb3%2Fap.png?alt=media&amp;token=79f84dd5-ec37-44fa-a449-917205933e53" alt=""><figcaption></figcaption></figure>

## 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 <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-api-secret>",
    "Content-Type": "multipart/form-data"
}
```

#### Request Body

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

```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<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

```json
{
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-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": "<PathToBrandImage>",
    "backgroundImage": "<PathToBackgroundImage>"
}
```

***

### 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 <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-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 <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-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 `<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

<table><thead><tr><th width="252">Parameter</th><th width="102">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td>Yes</td><td>ID of the application making the request</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>taskId</code></td><td>Yes</td><td>Unique identifier for the specific task</td><td><code>f3008b9d-dba7-471f-abc5-624a9c7d60d4</code></td></tr><tr><td><code>imageRenderProcessId</code></td><td>Yes</td><td>ID of the image rendering process</td><td><code>db2ff597-6c13-41f6-b0d6-5d0032de035b</code></td></tr><tr><td><code>lowResolution</code></td><td>No</td><td>Indicates whether the image is in low resolution</td><td><code>false</code></td></tr></tbody></table>

***

### Request Format

The request must include query parameters and required headers:

#### Request Headers

```json
{
    "Accept": "application/json",
    "Authorization": "Bearer <token>",
    "x-api-key": "<your-api-key>",
    "x-api-secret": "<your-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 <token>
x-api-key: <your-api-key>
x-api-secret: <your-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 <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**:

```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`.

***


# Image Upscaler API

The Image Upscaler feature allows clients to upscale images using advanced AI technology. This feature is accessible through RESTful API endpoints, supporting operations such as initiating an upscaling process, monitoring progress, and downloading the upscaled images.

***

### Endpoints Overview <a href="#endpoints-overview" id="endpoints-overview"></a>

#### 1. **Start Image Upscaling Process** <a href="#id-1-start-image-upscaling-process" id="id-1-start-image-upscaling-process"></a>

**Description:**\
Initiates the image upscaling process for a given image.

**Details:**\
**URL**:\
`POST /api/v1/Image/Upscaling/AdCreative`\
**Full Path**:\
`https://api.adcreative.ai/api/v1/Image/Upscaling/AdCreative`

**Authorization**:\
Requires a Bearer Token and the following headers:

| Header          | Description                     | Example Value                  |
| --------------- | ------------------------------- | ------------------------------ |
| `Authorization` | Bearer token for authentication | `Bearer YOUR_BEARER_TOKEN`     |
| `x-api-key`     | API Key for the application     | `a1c3b5d7e9f6a8c4d2e9b3f7c5a9` |
| `x-api-secret`  | Secret Key for the application  | `f5c6a7b8e9d4f1a3c7b6e8f3a9d5` |
| `Content-Type`  | Specifies the data format       | `multipart/form-data`          |
| `Accept`        | Expected response format        | `application/json`             |

**Request Body (form-data)**:

<table data-full-width="true"><thead><tr><th width="250">Field</th><th width="125">Type</th><th width="127">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>GUID</code></td><td>Yes</td><td>Unique identifier for the application initiating the request.</td></tr><tr><td><code>userId</code></td><td><code>GUID</code></td><td>Yes</td><td>Unique identifier for the user for whom the upscaling is performed.</td></tr><tr><td><code>uploadedImage</code></td><td><code>File</code></td><td>Yes</td><td>Image file to be upscaled (e.g., <code>.jpg</code> or <code>.png</code>).</td></tr></tbody></table>

***

#### Example Request

**cURL Command**:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/Upscaling/AdCreative' \\
--header 'Content-Type: multipart/form-data' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>' \\
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \\
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \\
--form 'uploadedImage=@"/path/to/your/image.jpg"'
```

***

#### Example Responses

**Successful Response**

**HTTP Status Code**: `200 OK`\
**Response Body**:

```json
{
  "$id": "1",
  "messageType": "ImageUpscalingProgress",
  "requestRenderState": 1,
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c",
  "totalTaskCount": 1,
  "completedTaskCount": 0,
  "progress": 0,
  "tasks": {
    "$id": "2",
    "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 1
  },
  "renderType": 8,
  "isSuccessful": true,
  "errorMessage": ""
}
```

***

**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",
    "UploadedImage": [
      "UploadedImage is required.",
      "The request does not contain a file. Please make sure to upload the file."
    ]
  },
  "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}
```

**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-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
  }
}
```

***

#### Notes on Errors

* **400 Bad Request**: Missing required fields or invalid image format.
* **401 Unauthorized**: Missing or invalid token, or incorrect API credentials.

Ensure all required fields are provided and valid.&#x20;

***

#### 2. **Check User Progress** <a href="#id-2-check-user-progress" id="id-2-check-user-progress"></a>

**Description:**\
Retrieves the progress of the upscaling process for a specific user.

**Details:**

* **URL**:\
  `GET /api/v1/Image/Upscaling/CheckUserProgress`
* **Full Path**:\
  `https://api.adcreative.ai/api/v1/Image/Upscaling/CheckUserProgress`
* **Authorization**:\
  Requires a Bearer Token and the following headers:

***

### Headers

<table data-full-width="true"><thead><tr><th width="245">Header Name</th><th width="278">Value</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer <code>&#x3C;YOUR_TOKEN></code></td><td>Required for authentication.</td></tr><tr><td>x-api-key</td><td><code>&#x3C;YOUR_API_KEY></code></td><td>API Key for accessing the endpoint.</td></tr><tr><td>x-api-secret</td><td><code>&#x3C;YOUR_API_SECRET></code></td><td>API Secret for accessing the endpoint.</td></tr><tr><td>Accept</td><td>application/json</td><td>Specifies the response format.</td></tr></tbody></table>

***

### Query Parameters

<table data-full-width="true"><thead><tr><th width="292">Parameter</th><th width="135">Type</th><th width="124">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier for the user.</td></tr><tr><td><code>imageUpscalerProcessId</code></td><td><code>Guid</code></td><td>No</td><td>(Optional) The ID of the specific upscaling process.</td></tr></tbody></table>

***

### Example Request

#### cURL Command:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/Upscaling/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageUpscalerProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

***

### Example Responses

#### Successful Response

* **HTTP Status Code**: `200 OK`
* **Response Body**:

```json
{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageUpscalingProgress",
            "requestRenderState": 5,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c",
            "totalTaskCount": 1,
            "completedTaskCount": 1,
            "progress": 100,
            "tasks": {
                "$id": "3",
                "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 5
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}
```

***

#### 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",
        "userId": [
            "The userId field is required."
        ]
    },
    "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}
```

***

#### 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-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}
```

***

### Notes on Errors

* **400 Bad Request**: Occurs when required parameters (`userId`) are missing or invalid.
* **401 Unauthorized**: Happens when the token is missing, invalid, or API credentials are incorrect.
* Ensure all required headers and query parameters are provided correctly.

***

#### 3. Check Application All Progresses <a href="#id-2-check-user-progress" id="id-2-check-user-progress"></a>

**Description:**\
Checks the progress of all image upscaling processes for a specific application.

**Details:**

* **Method**: `GET`
* **URL**: `/api/v1/Image/Upscaling/CheckApplicationAllProgresses`
* **Full Path**: `https://api.adcreative.ai/api/v1/Image/Upscaling/CheckApplicationAllProgresses`

### Authorization

* **Required**: Bearer Token
* **Headers**:
  * `Accept: application/json`
  * `Authorization: Bearer <YOUR_BEARER_TOKEN>`
  * `x-api-key: <YOUR_API_KEY>`
  * `x-api-secret: <YOUR_API_SECRET>`

### Query Parameters

| Parameter       | Type   | Required | Description                               |
| --------------- | ------ | -------- | ----------------------------------------- |
| `applicationId` | `Guid` | Yes      | The unique identifier of the application. |

### Example Request

#### cURL Command

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/Upscaling/CheckApplicationAllProgresses?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

### Responses

#### Successful Response

* **HTTP Status Code**: `200 OK`
* **Response Body**:

```json
{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageUpscalingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "0f2b39a9-104a-4b8c-b52e-d126413504ac",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "3",
                "8dffe58f-3ea7-45aa-ae76-5c4fe6945d86": 1
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        },
        {
            "$id": "4",
            "messageType": "ImageUpscalingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "b747fd87-0ebc-4112-afd0-53af8ce56ce7",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "5",
                "95c30efa-95cd-47d6-bb7a-fc5ca44fc3b5": 1
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}
```

#### 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": {
    "applicationId": ["The applicationId field is required."]
  },
  "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}
```

#### 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-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}
```

#### Not Found Error Response

* **HTTP Status Code**: `404 Not Found`
* **Response Body**:

```json
{
    "errors": {
        "engine: CheckProgress": [
            "No running or incomplete ImageFaceEnhancingProcess was not found for the User: N/A or the Application: b747fd87-0ebc-4112-afd0-53af8ce56ce7"
        ],
        "business: CheckApplicationAllProgresses": [
            "Not found error occurred while checking image upscaling process for the ApplicationId: b747fd87-0ebc-4112-afd0-53af8ce56ce7"
        ]
    },
    "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-1252ddef5b95d69e25141fc0ead96042-a0c01c9be85419ef-00"
    }
}
```

***

### Error Notes

* **400 Bad Request**: Occurs if `applicationId` is missing or invalid.
* **401 Unauthorized**: Bearer token is missing, invalid, or API credentials are incorrect.
* **404 Not Found**: No progress data is found for the provided `applicationId`.

***

#### 4. **Download Upscaled Image** <a href="#id-3-download-upscaled-image" id="id-3-download-upscaled-image"></a>

### Description:

Retrieves the upscaled image content stream based on the provided query parameters.

***

### Details:

* **Method:** `GET`
* **URL:** `/api/v1/Image/Upscaling/Download`
* **Full Path:** `https://api.adcreative.ai/api/v1/Image/Upscaling/Download`

***

### Authorization:

* Requires a Bearer Token.
* The following headers must be included:

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

<table data-full-width="true"><thead><tr><th width="255">Parameter</th><th width="83">Type</th><th width="98">Required</th><th width="250">Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>ID of the application making the request</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>taskId</code></td><td><code>Guid</code></td><td>Yes</td><td>Unique identifier for the specific task</td><td><code>e6c59f37-a794-234f-56yu-c9ef79dc042c</code></td></tr><tr><td><code>imageUpscalerProcessId</code></td><td><code>Guid</code></td><td>Yes</td><td>ID of the image upscaling process</td><td><code>e6c59f37-a794-468d-81aa-c9ef79dc042c</code></td></tr><tr><td><code>lowResolution</code></td><td><code>bool</code></td><td>No</td><td>Indicates whether the image is in low resolution</td><td><code>false</code></td></tr></tbody></table>

***

### Example Request:

**cURL Command:**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/Upscaling/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=e6c59f37-a794-234f-56yu-c9ef79dc042c&imageUpscalerProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c&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>'
```

***

### Example Responses:

#### **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-735817749634d9300906511b8291993f-15940a2feb6bac0a-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 'e6c59f37-a794-234f-56yu-c9ef79dc042c' is not valid."
        ]
    },
    "traceId": "00-7f9b779a099abe1bc26babff88ab4d5d-707fdfff822f63ed-00"
}
```

***

#### **Not Found Error Response:**

* **HTTP Status Code:** `404 Not Found`
* **Response Body:**

```json
{
    "errors": {
        "engine: Upscaling/Download": [
            "Image content not found."
        ],
        "business: Upscaling/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-87979cce38eb3aaa532fc90bdc73f9df-82aedb262968bc6a-00"
    }
}
```

***

### Error Notes:

* **400 Bad Request:**
  * Occurs when the `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 `imageUpscalerProcessId` are correct.
* **401 Unauthorized:**
  * Bearer token is missing or invalid.
  * Ensure proper API key and secret are used in the headers.

***

### **Validation Notes** <a href="#validation-notes" id="validation-notes"></a>

1. **Required Fields:** All required fields must be provided in the request.
2. **File Formats:** Uploaded files must meet the required formats (e.g., `jpeg`).
3. **Notification Channel:** If notifications are enabled, ensure a valid notification channel is configured.


# Background Remover API

The Background Remover feature allows clients to to remove backgrounds from images using advanced AI technology, preparing the images for creative enhancements. This feature is accessible through RESTful API endpoints, supporting operations such as initiating an background removing process, monitoring progress, and downloading the background removed images.

***

### Endpoints Overview <a href="#endpoints-overview" id="endpoints-overview"></a>

#### 1. **Start** BackgroundRemoving **Process** <a href="#id-1-start-image-upscaling-process" id="id-1-start-image-upscaling-process"></a>

**Description:**\
Initiates the background removing process for a given image.

**Details:**\
**URL**:\
`POST /api/v1/Image/BackgroundRemoving/AdCreative`\
**Full Path**:\
`https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/AdCreative`

**Authorization**:\
Requires a Bearer Token and the following headers:

| Header          | Description                     | Example Value                  |
| --------------- | ------------------------------- | ------------------------------ |
| `Authorization` | Bearer token for authentication | `Bearer YOUR_BEARER_TOKEN`     |
| `x-api-key`     | API Key for the application     | `a1c3b5d7e9f6a8c4d2e9b3f7c5a9` |
| `x-api-secret`  | Secret Key for the application  | `f5c6a7b8e9d4f1a3c7b6e8f3a9d5` |
| `Content-Type`  | Specifies the data format       | `multipart/form-data`          |
| `Accept`        | Expected response format        | `application/json`             |

**Request Body (form-data)**:

<table data-full-width="true"><thead><tr><th width="219">Field</th><th width="94">Type</th><th width="113">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>GUID</code></td><td>Yes</td><td>Unique identifier for the application initiating the request.</td></tr><tr><td><code>userId</code></td><td><code>GUID</code></td><td>Yes</td><td>Unique identifier for the user for whom the background removing is performed.</td></tr><tr><td><code>uploadedImage</code></td><td><code>File</code></td><td>Yes</td><td>Image file to be remove background (e.g., <code>.jpg</code> or <code>.png</code>).</td></tr></tbody></table>

***

#### Example Request

**cURL Command**:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/AdCreative' \\
--header 'Content-Type: multipart/form-data' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>' \\
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \\
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \\
--form 'uploadedImage=@"/path/to/your/image.jpg"'
```

***

#### Example Responses

**Successful Response**

**HTTP Status Code**: `200 OK`\
**Response Body**:

```json
{
  "$id": "1",
  "messageType": "ImageBackgroundRemovingProgress",
  "requestRenderState": 1,
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c",
  "totalTaskCount": 1,
  "completedTaskCount": 0,
  "progress": 0,
  "tasks": {
    "$id": "2",
    "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 1
  },
  "renderType": 8,
  "isSuccessful": true,
  "errorMessage": ""
}
```

***

**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",
    "UploadedImage": [
      "UploadedImage is required.",
      "The request does not contain a file. Please make sure to upload the file."
    ]
  },
  "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}
```

**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-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
  }
}
```

***

#### Notes on Errors

* **400 Bad Request**: Missing required fields or invalid image format.
* **401 Unauthorized**: Missing or invalid token, or incorrect API credentials.

Ensure all required fields are provided and valid.&#x20;

***

#### 2. **Check User Progress** <a href="#id-2-check-user-progress" id="id-2-check-user-progress"></a>

**Description:**\
Retrieves the progress of the background removing process for a specific user.

**Details:**

* **URL**:\
  `GET /api/v1/Image/BackgroundRemoving/CheckUserProgress`
* **Full Path**:\
  `https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckUserProgress`
* **Authorization**:\
  Requires a Bearer Token and the following headers:

***

### Headers

| Header Name   | Value                 | Description                            |
| ------------- | --------------------- | -------------------------------------- |
| Authorization | Bearer `<YOUR_TOKEN>` | Required for authentication.           |
| x-api-key     | `<YOUR_API_KEY>`      | API Key for accessing the endpoint.    |
| x-api-secret  | `<YOUR_API_SECRET>`   | API Secret for accessing the endpoint. |
| Accept        | application/json      | Specifies the response format.         |

***

### Query Parameters

<table data-full-width="true"><thead><tr><th width="340">Parameter</th><th width="114">Type</th><th width="101">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier for the user.</td></tr><tr><td><code>imageBackgroundRemoverProcessId</code></td><td><code>Guid</code></td><td>No</td><td>(Optional) The ID of the specific background removing process.</td></tr></tbody></table>

***

### Example Request

#### cURL Command:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageBackgroundRemoverProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

***

### Example Responses

#### Successful Response

* **HTTP Status Code**: `200 OK`
* **Response Body**:

```json
{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageBackgroundRemovingProgress",
            "requestRenderState": 5,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c",
            "totalTaskCount": 1,
            "completedTaskCount": 1,
            "progress": 100,
            "tasks": {
                "$id": "3",
                "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 5
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}
```

***

#### 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",
        "userId": [
            "The userId field is required."
        ]
    },
    "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}
```

***

#### 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-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}
```

***

### Notes on Errors

* **400 Bad Request**: Occurs when required parameters (`userId`) are missing or invalid.
* **401 Unauthorized**: Happens when the token is missing, invalid, or API credentials are incorrect.
* Ensure all required headers and query parameters are provided correctly.

***

#### 3. Check Application All Progresses <a href="#id-2-check-user-progress" id="id-2-check-user-progress"></a>

**Description:**\
Checks the progress of all image background removing processes for a specific application.

**Details:**

* **Method**: `GET`
* **URL**: `/api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses`
* **Full Path**: `https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses`

### Authorization

* **Required**: Bearer Token
* **Headers**:
  * `Accept: application/json`
  * `Authorization: Bearer <YOUR_BEARER_TOKEN>`
  * `x-api-key: <YOUR_API_KEY>`
  * `x-api-secret: <YOUR_API_SECRET>`

### Query Parameters

| Parameter       | Type   | Required | Description                               |
| --------------- | ------ | -------- | ----------------------------------------- |
| `applicationId` | `Guid` | Yes      | The unique identifier of the application. |

### Example Request

#### cURL Command

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

### Responses

#### Successful Response

* **HTTP Status Code**: `200 OK`
* **Response Body**:

```json
{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageBackgroundRemovingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "0f2b39a9-104a-4b8c-b52e-d126413504ac",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "3",
                "8dffe58f-3ea7-45aa-ae76-5c4fe6945d86": 1
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        },
        {
            "$id": "4",
            "messageType": "ImageBackgroundRemovingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "b747fd87-0ebc-4112-afd0-53af8ce56ce7",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "5",
                "95c30efa-95cd-47d6-bb7a-fc5ca44fc3b5": 1
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}
```

#### 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": {
    "applicationId": ["The applicationId field is required."]
  },
  "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}
```

#### 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-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}
```

#### Not Found Error Response

* **HTTP Status Code**: `404 Not Found`
* **Response Body**:

```json
{
    "errors": {
        "engine: CheckProgress": [
            "No running or incomplete ImageFaceEnhancingProcess was not found for the User: N/A or the Application: b747fd87-0ebc-4112-afd0-53af8ce56ce7"
        ],
        "business: CheckApplicationAllProgresses": [
            "Not found error occurred while checking image background removing process for the ApplicationId: b747fd87-0ebc-4112-afd0-53af8ce56ce7"
        ]
    },
    "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-1252ddef5b95d69e25141fc0ead96042-a0c01c9be85419ef-00"
    }
}
```

***

### Error Notes

* **400 Bad Request**: Occurs if `applicationId` is missing or invalid.
* **401 Unauthorized**: Bearer token is missing, invalid, or API credentials are incorrect.
* **404 Not Found**: No progress data is found for the provided `applicationId`.

***

#### 4. **Download Background Removed Image** <a href="#id-3-download-upscaled-image" id="id-3-download-upscaled-image"></a>

### Description:

Retrieves the background removed image content stream based on the provided query parameters.

***

### Details:

* **Method:** `GET`
* **URL:** `/api/v1/Image/BackgroundRemoving/Download`
* **Full Path:** `https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/Download`

***

### Authorization:

* Requires a Bearer Token.
* The following headers must be included:

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

<table data-full-width="true"><thead><tr><th width="270">Parameter</th><th width="83">Type</th><th width="106">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>ID of the application making the request</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>taskId</code></td><td><code>Guid</code></td><td>Yes</td><td>Unique identifier for the specific task</td><td><code>e6c59f37-a794-234f-56yu-c9ef79dc042c</code></td></tr><tr><td><p><code>imageBackgroundRemover</code></p><p><code>ProcessId</code></p></td><td><code>Guid</code></td><td>Yes</td><td>ID of the image background removing process</td><td><code>e6c59f37-a794-468d-81aa-c9ef79dc042c</code></td></tr><tr><td><code>lowResolution</code></td><td><code>bool</code></td><td>No</td><td>Indicates whether the image is in low resolution</td><td><code>false</code></td></tr></tbody></table>

***

### Example Request:

**cURL Command:**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=e6c59f37-a794-234f-56yu-c9ef79dc042c&imageBackgroundRemoverProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c&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>'
```

***

### Example Responses:

#### **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-735817749634d9300906511b8291993f-15940a2feb6bac0a-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 'e6c59f37-a794-234f-56yu-c9ef79dc042c' is not valid."
        ]
    },
    "traceId": "00-7f9b779a099abe1bc26babff88ab4d5d-707fdfff822f63ed-00"
}
```

***

#### **Not Found Error Response:**

* **HTTP Status Code:** `404 Not Found`
* **Response Body:**

```json
{
    "errors": {
        "engine: BackgroundRemoving/Download": [
            "Image content not found."
        ],
        "business: BackgroundRemoving/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-87979cce38eb3aaa532fc90bdc73f9df-82aedb262968bc6a-00"
    }
}
```

***

### Error Notes:

* **400 Bad Request:**
  * Occurs when the `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 `imageBackgroundRemoverProcessId` are correct.
* **401 Unauthorized:**
  * Bearer token is missing or invalid.
  * Ensure proper API key and secret are used in the headers.

***

### **Validation Notes** <a href="#validation-notes" id="validation-notes"></a>

1. **Required Fields:** All required fields must be provided in the request.
2. **File Formats:** Uploaded files must meet the required formats (e.g., `jpeg`).
3. **Notification Channel:** If notifications are enabled, ensure a valid notification channel is configured.


# Face Enhancer API

The Face Enhancer feature allows clients to enhance faces in images using advanced AI technology. This feature is accessible through RESTful API endpoints, supporting operations such as initiating a face enhancing process, monitoring progress, and downloading the face enhanced images.

### Endpoints Overview <a href="#endpoints-overview" id="endpoints-overview"></a>

#### 1. Start Face Enhancing Process

**Description:**\
Initiates the face enhancing process for a given image.

**Details:**

* **URL:** `POST /api/v1/Image/FaceEnhancing/AdCreative`
* **Full Path:** `https://api.adcreative.ai/api/v1/Image/FaceEnhancing/AdCreative`

**Authorization:**\
Requires a Bearer Token and the following headers:

<table><thead><tr><th>Header</th><th width="274">Description</th><th>Example Value</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer token for authentication</td><td>Bearer <code>&#x3C;YOUR_BEARER_TOKEN></code></td></tr><tr><td>x-api-key</td><td>API Key for the application</td><td><code>&#x3C;YOUR_API_KEY></code></td></tr><tr><td>x-api-secret</td><td>Secret Key for the application</td><td><code>&#x3C;YOUR_API_SECRET></code></td></tr><tr><td>Content-Type</td><td>Specifies the data format</td><td><code>multipart/form-data</code></td></tr><tr><td>Accept</td><td>Expected response format</td><td><code>application/json</code></td></tr></tbody></table>

**Request Body (form-data):**

| Field         | Type    | Required | Description                                                                |
| ------------- | ------- | -------- | -------------------------------------------------------------------------- |
| applicationId | GUID    | Yes      | Unique identifier for the application initiating the request.              |
| userId        | GUID    | Yes      | Unique identifier for the user for whom the face enhancement is performed. |
| ariaRatio     | Float   | No       | Ratio for face enhancement area adjustment (default: `0.5`).               |
| maxFaceCount  | Integer | No       | Maximum number of faces to enhance (default: `10`).                        |
| uploadedImage | File    | Yes      | Image file to be enhanced (e.g., `.jpg` or `.png`).                        |

**Example Request:**\
cURL Command:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/AdCreative' \\
--header 'Content-Type: multipart/form-data' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>' \\
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \\
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \\
--form 'ariaRatio="0.5"' \\
--form 'maxFaceCount="10"' \\
--form 'uploadedImage=@"/Users/adcreative.ai/Downloads/Images/group_bad_faces.png"'
```

**Example Responses:**

* **Successful Response:**\
  HTTP Status Code: `200 OK`\
  Response Body:

  ```json
  {
    "$id": "1",
    "messageType": "ImageFaceEnhancingProgress",
    "requestRenderState": 1,
    "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
    "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "imageRenderProcessId": "c61259ee-ba2d-49ef-9f58-9b2e7d4ad7ab",
    "totalTaskCount": 1,
    "completedTaskCount": 0,
    "progress": 0,
    "tasks": {
      "$id": "2",
      "8f8c84c6-1df7-41a8-9c72-855221f8b7ef": 1
    },
    "renderType": 128,
    "isSuccessful": true,
    "errorMessage": ""
  }
  ```
* **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",
      "UploadedImage": [
        "UploadedImage is required.",
        "The request does not contain a file. Please make sure to upload the file."
      ]
    },
    "traceId": "00-ce239b46f43de0766c9b9ce3d272a92a-7eab8b88dd249512-00"
  }
  ```
* **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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-00"
    }
  }
  ```

**Notes on Errors:**

* **400 Bad Request:** Missing required fields or invalid image format.
* **401 Unauthorized:** Missing or invalid token, or incorrect API credentials. Ensure all required fields are provided and valid.

***

### 2. Check User Progress

#### Description:

Retrieves the progress of the face enhancement process for a specific user.

#### Details:

* **Method:** GET
* **URL:** `/api/v1/Image/FaceEnhancing/CheckUserProgress`
* **Full Path:** `https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckUserProgress`

#### Authorization:

Requires a Bearer Token with the following headers:

| Header        | Value                 | Description                            |
| ------------- | --------------------- | -------------------------------------- |
| Authorization | Bearer `<YOUR_TOKEN>` | Required for authentication.           |
| x-api-key     | `<YOUR_API_KEY>`      | API Key for accessing the endpoint.    |
| x-api-secret  | `<YOUR_API_SECRET>`   | API Secret for accessing the endpoint. |
| Accept        | `application/json`    | Specifies the response format.         |

#### Query Parameters:

| Parameter                  | Type | Required | Description                                                 |
| -------------------------- | ---- | -------- | ----------------------------------------------------------- |
| userId                     | Guid | Yes      | The unique identifier for the user.                         |
| imageFaceEnhancerProcessId | Guid | No       | (Optional) The ID of the specific face enhancement process. |

#### Example Request:

**cURL Command:**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageFaceEnhancerProcessId=2c3a9038-a7c8-4a8a-8821-a66dc433c3dd' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

#### Example Responses:

**Successful Response:**

**HTTP Status Code:** `200 OK`

**Response Body:**

```json
{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageFaceEnhancingProgress",
            "requestRenderState": 5,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "2c3a9038-a7c8-4a8a-8821-a66dc433c3dd",
            "totalTaskCount": 1,
            "completedTaskCount": 1,
            "progress": 100,
            "tasks": {
                "$id": "3",
                "165ce0c4-27a4-4317-a388-3c4064cf8b17": 5
            },
            "renderType": 128,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}
```

**Validation Error Response:**

**HTTP Status Code:** `400 Bad Request`

**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-2963f16f8ef6ed45095d4ceab4aa4be3-5d89071342730431-00"
    }
}
```

**Not Found Error Response:**

**HTTP Status Code:** `404 Not Found`

**Response Body:**

```json
{
    "errors": {
        "engine: CheckProgress": [
            "No running or incomplete ImageFaceEnhancingProcess was not found for the User: 2581c740-8e9d-4d63-96bc-5665bb9a646b or the Application: N/A"
        ],
        "business: CheckUserProgress": [
            "Not found error occurred while checking face enhancer process for User: 2581c740-8e9d-4d63-96bc-5665bb9a646b and imageFaceEnhancerProcessId: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ]
    },
    "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-3a592608499e51142589ccee0ad1118a-d18b65bd224535c3-00"
    }
}
```

#### Notes on Errors:

* **400 Bad Request:** Occurs when required parameters (e.g., `userId`) are missing or invalid.
* **404 Not Found:** No progress data is found for the provided `userId` or `imageFaceEnhancerProcessId`.
* **401 Unauthorized:** Bearer token is missing or invalid.

***

#### 3. Check Application Progress <a href="#id-3-check-application-progress" id="id-3-check-application-progress"></a>

#### Description

Checks the progress of all face-enhancing processes for a specific application.

#### Endpoint Details

* **Method**: GET
* **URL**: `/api/v1/Image/FaceEnhancing/CheckApplicationAllProgresses`
* **Full Path**: `https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckApplicationAllProgresses`

#### Authorization

Requires a Bearer Token.

**Headers**

| 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

<table><thead><tr><th width="144">Parameter</th><th width="78">Type</th><th width="99">Required</th><th width="196">Description</th><th>Example Value</th></tr></thead><tbody><tr><td>applicationId</td><td>Guid</td><td>Yes</td><td>ID of the application making the request</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr></tbody></table>

#### Example Request

**cURL Command:**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckApplicationAllProgresses?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

#### Example Responses

**Successful Response:**

* **HTTP Status Code**: 200 OK
* **Response Body**:

```json
{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageFaceEnhancingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "6dc55293-8c07-4522-950f-265fd38c733c",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "3",
                "828a7a62-5462-4fea-9416-642bf201acf7": 1
            },
            "renderType": 128,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}
```

**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",
        "applicationId": [
            "The value '2581c740-8e9d-4d63-96bc-5665bb9a6' is not valid."
        ]
    },
    "traceId": "00-f63a19f0239297745f0493e1ff93f582-3e5099e2cbe621ce-00"
}
```

**Not Found Error Response:**

* **HTTP Status Code**: 404 Not Found
* **Response Body**:

```json
{
    "errors": {
        "engine: CheckProgress": [
            "No running or incomplete ImageFaceEnhancingProcess was not found for the User: N/A or the Application: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ],
        "business: CheckApplicationAllProgresses": [
            "Not found error occurred while checking image face enhancing process for the ApplicationId: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ]
    },
    "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-8d925e3ff2b520c283a3fbd504172fce-1df96f7a708f401d-00"
    }
}
```

**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-95ba97c088b871449fe76ced5f3977a9-7bb06405ad7dce6c-00"
    }
}
```

#### Error Notes

* **400 Bad Request**: Occurs if applicationId is missing or invalid. Ensure the applicationId is a valid GUID.
* **404 Not Found**: No progress data is found for the provided applicationId.
* **401 Unauthorized**: Bearer token is missing or invalid. Ensure proper API key and secret are used in the headers.

***

#### 4. Download Face Enhanced Image <a href="#id-4-download-face-enhanced-image" id="id-4-download-face-enhanced-image"></a>

### Endpoint Details

**Method**: `GET`\
**URL**: `/api/v1/Image/FaceEnhancing/Download`\
**Full Path**: `https://api.adcreative.ai/api/v1/Image/FaceEnhancing/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

<table><thead><tr><th width="226">Parameter</th><th width="95">Type</th><th width="113">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>ID of the application making the request</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>taskId</code></td><td><code>Guid</code></td><td>Yes</td><td>Unique identifier for the specific task</td><td><code>165ce0c4-27a4-4317-a388-3c4064cf8b17</code></td></tr><tr><td><code>imageFaceEnhancerProcessId</code></td><td><code>Guid</code></td><td>Yes</td><td>ID of the face-enhancing process</td><td><code>2c3a9038-a7c8-4a8a-8821-a66dc433c3dd</code></td></tr><tr><td><code>lowResolution</code></td><td><code>bool</code></td><td>No</td><td>Indicates whether the image is in low resolution</td><td><code>true</code></td></tr></tbody></table>

***

### Example Request

**cURL Command**:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=165ce0c4-27a4-4317-a388-3c4064cf8b17&imageFaceEnhancerProcessId=2c3a9038-a7c8-4a8a-8821-a66dc433c3dd&lowResolution=true' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

***

### Example Responses

#### 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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-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 '165ce0c4-27a4-4317-a388-3c4064cf8b' is not valid."
        ]
    },
    "traceId": "00-a54a3264785cd30b4ee7e454053096bf-0b0d3b01c3bcd870-00"
}
```

***

#### Not Found Error Response

**HTTP Status Code**: `404 Not Found`\
**Response Body**:

```json
{
    "errors": {
        "engine: FaceEnhancing/Download": [
            "Image content not found."
        ],
        "business: FaceEnhancing/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-80d865ee86529038daf1fef33992439c-4defb5fc45a4f77e-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 `imageFaceEnhancerProcessId` are correct.
* **401 Unauthorized**:
  * Bearer token is missing or invalid.
  * Ensure proper API key and secret are used in the headers.

***

### Validation Notes

* **Required Fields**: All required fields must be provided in the request.
* **Notification Channel**: If notifications are enabled, ensure a valid notification channel is configured.

***

### Additional Notes <a href="#additional-notes" id="additional-notes"></a>

* **Notification Requirement:** Ensure that an active notification channel is configured for the application before calling these endpoints.
* **Validation:** Validate all GUIDs and required parameters before making API calls.


# Scan My Website API

### Overview

The **Scan My Website** feature utilizes AI to analyze the given website URL and extract valuable information such as:

* Brand description, name, and type
* Logo URLs and raw SVGs
* Website main colors and a comprehensive color palette

This feature provides insights that are valuable for branding and design purposes.

***

### Endpoint Information

**HTTP Method**: `GET`\
**URL**: `/api/v1/ScanMyWebsite`\
**Full URL**: `https://api.adcreative.ai/api/v1/ScanMyWebsite`

#### Authorization

This endpoint requires the following headers:

* `Authorization: Bearer <token>`
* `x-api-key: <your-api-key>`
* `x-api-secret: <your-api-secret>`

***

<table><thead><tr><th width="175">Header</th><th width="168">Description</th><th>Example</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer Token</td><td><code>Authorization: Bearer &#x3C;your-token></code></td></tr><tr><td>x-api-key</td><td>API Key</td><td><code>x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4</code></td></tr><tr><td>x-api-secret</td><td>API Secret</td><td><code>x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9</code></td></tr></tbody></table>

***

### Query Parameters

<table><thead><tr><th width="240">Parameter</th><th width="102">Type</th><th width="106">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique ID of the application.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique ID of the user.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>url</code></td><td><code>string</code></td><td>Yes</td><td>The website URL to scan.</td><td><code>https://fireflies.ai</code></td></tr><tr><td><code>includeLogoContent</code></td><td><code>bool</code></td><td>No</td><td>Whether to include the logo image bytes.</td><td><code>true</code></td></tr><tr><td><code>advanceMode</code></td><td><code>bool</code></td><td>No</td><td>Enables advanced mode for analysis.</td><td><code>false</code></td></tr></tbody></table>

***

### Example Requests

#### Curl Example

```bash
curl --location 'https://api.adcreative.ai/api/v1/ScanMyWebsite?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&url=https://fireflies.ai&includeLogoContent=true&advanceMode=false' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <token>' \\
--header 'x-api-key: <your-api-key>' \\
--header 'x-api-secret: <your-api-secret>'
```

#### HTTP Request Example

```http
GET /api/v1/ScanMyWebsite?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&url=https://fireflies.ai&includeLogoContent=true&advanceMode=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
```

***

### Example JSON Responses

#### Successful Response

**HTTP Status Code**: `200 OK`\
**Response Body**:

```json
{
    "brandLogos": {
        "logos": [
            "https://fireflies.ai/logo1.png",
            "https://fireflies.ai/logo2.png"
        ],
        "rawSvgIds": []
    },
    "firstLogoContent": "<base64-image-bytes>",
    "brandDescription": {
        "brandName": "Fireflies",
        "brandType": "Software as a Service (SaaS)",
        "brandDescription": "Fireflies.ai is an AI-powered notetaking platform."
    },
    "websiteColors": {
        "mainColors": ["#007bff", "#212529", "#6c757d"]
    },
    "colorsPalette": [
        ["#007bff", "#1a1f27"],
        ["#212529", "#ff6b6b"]
    ]
}
```

***

#### 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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-00"
    }
}
```

***

#### Validation Error Response

**HTTP Status Code**: `400 Bad Request`\
**Response Body**:

```json
{
    "errors": {
        "engine: ScanMyWebsite": [
            "The provided URL is invalid or not an absolute URL."
        ],
        "business: ScanMyWebsite": [
            "Bad request error occurred while scanning the website for the Application: d5eabbb8-c0f6-4640-94fd-3566edad499f and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b with the Url: auchan.fr"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 400,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-d142ce123ea6b6d9fa4b8ea74a1d7838-549229b6351e0557-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",
        "userId": [
            "The value '2581c740-8e9d-4d63-96bc-5665bb9' is not valid."
        ]
    },
    "traceId": "00-c80817b5043d40808a7a26de5709b4de-37eb0d01b96e3768-00"
}
```

***

### Additional Details

#### Validation

* Ensure the `url` is a valid, absolute URL.
* Provide valid `applicationId` and `userId` values.
* Large websites may take longer to process, particularly in `advanceMode`.

***


# Stock Image Generation API

### Introduction

***

The Stock Image Generation API leverages artificial intelligence to generate stock images based on user-provided prompts, styles, and other parameters. This document provides detailed information about the API, including endpoint descriptions, parameters, usage examples, and error responses.

***

#### Key Features:

* Generate stock images with user-defined prompts.
* Customize the image style using predefined options or example images.
* Support for LoRA parameters to fine-tune image generation.

***

### Endpoint: Start Stock Image Generation Process

**URL:** `/api/v1/Image/StockGeneration/AdCreative`

**Method:** `POST`

**Full URL:** `https://api.adcreative.ai/api/v1/Image/StockGeneration/AdCreative`

***

#### **Description**

This endpoint generates stock images based on the user's input prompt, style preferences, and optional parameters such as a custom style image or description.

***

**Authorization:** Requires a Bearer Token and the following headers:

<table data-full-width="false"><thead><tr><th>Header</th><th width="274">Description</th><th>Example Value</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer token for authentication</td><td>Bearer <code>&#x3C;YOUR_BEARER_TOKEN></code></td></tr><tr><td>x-api-key</td><td>API Key for the application</td><td><code>&#x3C;YOUR_API_KEY></code></td></tr><tr><td>x-api-secret</td><td>Secret Key for the application</td><td><code>&#x3C;YOUR_API_SECRET></code></td></tr><tr><td>Content-Type</td><td>Specifies the data format</td><td><code>multipart/form-data</code></td></tr><tr><td>Accept</td><td>Expected response format</td><td><code>application/json</code></td></tr></tbody></table>

***

#### **Parameters**

<table data-full-width="true"><thead><tr><th width="194">Parameter</th><th width="106">Type</th><th width="290">Description</th><th width="121">Required</th><th>Notes</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Application ID initiating the request.</td><td>Yes</td><td>Must be a non-empty GUID.</td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>User ID for whom the image generation is being performed.</td><td>Yes</td><td>Must be a non-empty GUID.</td></tr><tr><td><code>renderKind</code></td><td><code>Enum</code></td><td>Render kind (e.g., Post, Story). Specifies the type of render. Accepted values are defined in the <code>RenderKind</code> enum.</td><td>Yes</td><td>See RenderKind values in "Enums and Descriptions" page.</td></tr><tr><td><code>imageStyle</code></td><td><code>Enum</code></td><td>Style of the generated image (e.g., Photorealistic, CustomWithText. Default: <code>3</code> "Photorealistic")</td><td>Yes</td><td>Default: Photorealistic. See ImageStyle values in "Enums and Descriptions" page.</td></tr><tr><td><code>userPrompt</code></td><td><code>String</code></td><td>Description of the desired stock image.</td><td>Yes</td><td>Max length: 1000 characters.</td></tr><tr><td><code>customStyleText</code></td><td><code>String</code></td><td>Text description of the desired custom style.</td><td>Conditional</td><td>Required if <code>imageStyle</code> is <code>CustomWithText</code>. Max length: 1000 characters.</td></tr><tr><td><code>customStyleImage</code></td><td><code>File</code></td><td>Image file to transfer its style from.</td><td>Conditional</td><td>Required if <code>imageStyle</code> is <code>CustomWithImage</code>.</td></tr><tr><td><code>loraParams</code></td><td><code>String</code></td><td>Lora parameters as key-value pairs for additional AI parameters.</td><td>No</td><td>Example format: <code>GUID1:float,GUID2:float</code></td></tr></tbody></table>

***

#### **Parameter Notes**

**ImageStyle Parameter**

The behavior of the `imageStyle` parameter changes based on its value:

* **CustomWithText**: Requires the `customStyleText` parameter to be provided. If not, a `400 Bad Request` error is returned with the message:
  * *"CustomStyleText can't be null or empty if ImageStyle is CustomWithText"*
* **CustomWithImage**: Requires the `customStyleImage` parameter to be provided. If not, a `400 Bad Request` error is returned with the message:
  * *"CustomWithImage can't be null if ImageStyle is CustomWithImage"*

***

#### **Request Example**

#### Sample HTTP Client Request

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.adcreative.ai/api/v1/Image/StockGeneration/AdCreative");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("x-api-key", "your-api-key");
request.Headers.Add("x-api-secret", "your-api-secret");
var content = new MultipartFormDataContent
{
    { new StringContent("4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"), "applicationId" },
    { new StringContent("2581c740-8e9d-4d63-96bc-5665bb9a646b"), "userId" },
    { new StringContent("1"), "renderKind" },
    { new StringContent("3"), "imageStyle" },
    { new StringContent("Darth Vader"), "userPrompt" }
};
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

**Curl**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/StockGeneration/AdCreative' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your_Token>' \
--header 'x-api-key: <your_x-api-key>' \
--header 'x-api-secret: <your_x-api-secret>'
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'renderKind=1' \
--form 'imageStyle=3' \
--form 'userPrompt="Darth Vader"' \
--form 'customStyleText="Serious looking"' \
--form 'customStyleImage=@"/path/to/image.jpg"' \
--form 'loraParams="e2b3c5d1-a123-456b-c789-d12345678901:0.75,a4b2c6d3-e234-567c-d890-f23456789012:1.0"'
```

**HTTP Request**

```http
POST /api/v1/Image/StockGeneration/AdCreative HTTP/1.1
Host: api.adcreative.ai
Accept: application/json
Authorization: Bearer <Your_Token>
x-api-key: <your_x-api-key>
x-api-secret: <your_x-api-secret>
Content-Type: multipart/form-data

applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId=2581c740-8e9d-4d63-96bc-5665bb9a646b
renderKind=1
imageStyle=3
userPrompt=Darth Vader
customStyleText=Serious looking
customStyleImage=<file>
loraParams=e2b3c5d1-a123-456b-c789-d12345678901:0.75,a4b2c6d3-e234-567c-d890-f23456789012:1.0
```

***

#### **Response Examples**

**200 OK**

```json
{
    "messageType": "ImageStockGenerationProgress",
    "requestRenderState": 1,
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "imageRenderProcessId": "0898d00e-4a06-4d3d-b7c5-96116286449e",
    "totalTaskCount": 1,
    "completedTaskCount": 0,
    "progress": 0,
    "tasks": {
        "530286a9-7adb-49e0-a66d-065cbb52fecc": 1
    },
    "renderType": 32,
    "isSuccessful": false,
    "errorMessage": ""
}
```

#### Bad Request (400)

**Example 1**

```json
{
    "errors": {
        "engine: StockGeneration/AdCreative": [
            "CustomWithImage can't be null if ImageStyle is CustomWithImage"
        ],
        "business: StockGeneration/AdCreative": [
            "Bad request error occurred while starting image stock generation process"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 400,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-3bbaf2bdb083fbf5b8d96a25830005ca-adee457f95c76f15-00"
    }
}
```

**Example 2**

```json
{
    "errors": {
        "engine: StockGeneration/AdCreative": [
            "CustomStyleText can't be null or empty if ImageStyle is CustomWithText"
        ],
        "business: StockGeneration/AdCreative": [
            "Bad request error occurred while starting image stock generation process"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 400,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-9c92e7330476cab570f09bde47f59f47-d0040fb4d3c039c8-00"
    }
}
```

**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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-00"
    }
}
```

***

#### **Notes**

* Ensure all required parameters are provided.
* Validate combinations of `imageStyle`, `customStyleText`, and `customStyleImage` to avoid errors.
* Use appropriate headers for authentication and content type.

## CheckUserProgress and CheckApplicationAllProgresses Endpoints

### Overview

These endpoints allow clients to track the progress of stock image generation processes either for a specific user or for an entire application. The endpoints provide details about ongoing or completed image stock generation processes.

***

### **CheckUserProgress**

#### Endpoint

* **HTTP Method**: GET
* **URL**: `/api/v1/Image/StockGeneration/CheckUserProgress`
* **Full Path**: `https://api.adcreative.ai/api/v1/Image/StockGeneration/CheckUserProgress`

#### Authorization

* **Type**: Bearer Token

#### Query Parameters

<table><thead><tr><th width="237">Name</th><th width="86">Type</th><th width="104">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>userId</code></td><td>Guid</td><td>Yes</td><td>The unique identifier of the user whose stock image generation progress is being queried.</td></tr><tr><td><p><code>imageStockGenerator</code></p><p><code>ProcessId</code></p></td><td>Guid</td><td>No</td><td>The unique identifier of a specific stock image generation process for the user.</td></tr></tbody></table>

***

#### Request Examples

**CURL Example**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/StockGeneration/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageStockGeneratorProcessId=26eca5df-b455-4111-847a-84247bc8e594' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>'
--header 'x-api-key: <your_x-api-key>' \
--header 'x-api-secret: <your_x-api-secret>'
```

**HTTPClient Example**

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.adcreative.ai/api/v1/Image/StockGeneration/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageStockGeneratorProcessId=26eca5df-b455-4111-847a-84247bc8e594");
request.Headers.Add("Accept", "application/json");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<TOKEN>");
request.Headers.Add("x-api-key", "<your_x-api-key>");
request.Headers.Add("x-api-secret", "<your_x-api-secret>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

***

#### Responses

**Success (200 OK)**

```json
[
  {
    "messageType": "ImageStockGenerationProgress",
    "requestRenderState": 5,
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "imageRenderProcessId": "0898d00e-4a06-4d3d-b7c5-96116286449e",
    "totalTaskCount": 1,
    "completedTaskCount": 1,
    "progress": 100,
    "tasks": {
        "530286a9-7adb-49e0-a66d-065cbb52fecc": 5
    },
    "renderType": 32,
    "isSuccessful": true,
    "errorMessage": ""
  }
]
```

**Validation Error (400 Bad Request)**

```json
{
    "errors": {
        "business: StockGeneration/CheckUserProgress": [
            "Invalid userId or imageStockGeneratorProcessId provided."
        ],
        "engine: StockGeneration/CheckProgress": [
            "A required parameter is missing."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 400,
    "detail": "Validation error in the request parameters.",
    "instance": null,
    "extensions": {
        "traceId": "00-abcdef1234567890abcdef1234567890-abcdef1234567890-00"
    }
}
```

**Authentication Error (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-2963f16f8ef6ed45095d4ceab4aa4be3-5d89071342730431-00"
    }
}
```

***

### **CheckApplicationAllProgresses**

#### Endpoint

* **HTTP Method**: GET
* **URL**: `/api/v1/Image/StockGeneration/CheckApplicationAllProgresses`
* **Full Path**: `https://api.adcreative.ai/api/v1/Image/StockGeneration/CheckApplicationAllProgresses`

#### Authorization

* **Type**: Bearer Token

#### Query Parameters

<table><thead><tr><th width="189">Name</th><th width="82">Type</th><th width="99">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td>Guid</td><td>Yes</td><td>The unique identifier of the application for which the stock image generation progress is being queried.</td></tr></tbody></table>

***

#### Request Examples

**CURL Example**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/StockGeneration/CheckApplicationAllProgresses?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>'
--header 'x-api-key: <your_x-api-key>' \
--header 'x-api-secret: <your_x-api-secret>'
```

**HTTPClient Example**

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.adcreative.ai/api/v1/Image/StockGeneration/CheckApplicationAllProgresses?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f");
request.Headers.Add("Accept", "application/json");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<TOKEN>");
request.Headers.Add("x-api-key", "<your_x-api-key>");
request.Headers.Add("x-api-secret", "<your_x-api-secret>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

***

#### Responses

**Success (200 OK)**

```json
[
  {
      "messageType": "ImageStockGenerationProgress",
      "requestRenderState": 1,
      "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
      "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
      "imageRenderProcessId": "63dd1bff-8396-41d0-ba89-3406a27179cc",
      "totalTaskCount": 1,
      "completedTaskCount": 0,
      "progress": 0,
      "tasks": {
          "54f61fb3-114a-4eb1-b4ce-263c7298efa3": 1
      },
      "renderType": 32,
      "isSuccessful": false,
      "errorMessage": ""
  },
  {
      "messageType": "ImageStockGenerationProgress",
      "requestRenderState": 1,
      "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
      "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
      "imageRenderProcessId": "b3a0ce72-a4cb-4651-b128-b465a4b36b17",
      "totalTaskCount": 1,
      "completedTaskCount": 0,
      "progress": 0,
      "tasks": {
          "0f5f6dce-09ba-4287-ac2c-799aa607cb63": 1
      },
      "renderType": 32,
      "isSuccessful": false,
      "errorMessage": ""
  }
]
```

**Validation Error (400 Bad Request)**

```json
{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "applicationId": [
            "The value '2581c740-8e9d-4d63-96bc-5665bb9a6' is not valid."
        ]
    },
    "traceId": "00-f63a19f0239297745f0493e1ff93f582-3e5099e2cbe621ce-00"
}
```

**Not Found Error (404 Not Found)**

```json
{
    "errors": {
        "engine: CheckProgress": [
            "No running or incomplete Stock Image Generation process was not found for the User: N/A or the Application: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ],
        "business: CheckApplicationAllProgresses": [
            "Not found error occurred while checking Stock Image Generation process for the ApplicationId: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ]
    },
    "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-8d925e3ff2b520c283a3fbd504172fce-1df96f7a708f401d-00"
    }
}
```

***

## Download

### Description

Retrieves the generated stock image content stream based on the provided query parameters.

***

### Endpoint Details

**Method**: `GET`\
**URL**: `/api/v1/Image/StockGeneration/Download`\
**Full Path**: `https://api.adcreative.ai/api/v1/Image/StockGeneration/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

<table data-full-width="true"><thead><tr><th width="204">Parameter</th><th width="97">Type</th><th width="102">Required</th><th width="276">Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>ID of the application making the request</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>taskId</code></td><td><code>Guid</code></td><td>Yes</td><td>Unique identifier for the specific task</td><td><code>165ce0c4-27a4-4317-a388-3c4064cf8b17</code></td></tr><tr><td><p>imageStockGenerator</p><p>ProcessId</p></td><td><code>Guid</code></td><td>Yes</td><td>ID of the stock generation process</td><td><code>2c3a9038-a7c8-4a8a-8821-a66dc433c3dd</code></td></tr><tr><td><code>lowResolution</code></td><td><code>bool</code></td><td>No</td><td>Indicates whether the image is in low resolution</td><td><code>true</code></td></tr></tbody></table>

***

### Example Request

**cURL Command**:

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/StockGeneration/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=165ce0c4-27a4-4317-a388-3c4064cf8b17&imageStockGeneratorProcessId=2c3a9038-a7c8-4a8a-8821-a66dc433c3dd&lowResolution=true' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'
```

***

### Example Responses

#### 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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-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 '165ce0c4-27a4-4317-a388-3c4064cf8b' is not valid."
        ]
    },
    "traceId": "00-a54a3264785cd30b4ee7e454053096bf-0b0d3b01c3bcd870-00"
}
```

***

#### Not Found Error Response

**HTTP Status Code**: `404 Not Found`\
**Response Body**:

```json
{
    "errors": {
        "engine: StockGeneration/Download": [
            "Image content not found."
        ],
        "business: StockGeneration/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-80d865ee86529038daf1fef33992439c-4defb5fc45a4f77e-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 imageStockGeneratorProcessId are correct.
* **401 Unauthorized**:
  * Bearer token is missing or invalid.
  * Ensure proper API key and secret are used in the headers.

***

### Notes

1. Ensure that both `userId` and `applicationId` parameters are valid GUIDs.
2. For best practices, always verify the authorization token validity before making a request.
3. Logging is performed for all scenarios, including successful and error cases.

***


# Ad Text Generation API

Harness the capabilities of AdLLM™, our proprietary AI model trained on over a billion high-converting ad texts, to create compelling and impactful ad copy effortlessly.

### Overview

The **Ad Text Generation API** is a core feature designed to generate **conversion-focused ad texts** with the power of **AdLLM Spark** — the first **AdLLM** built specifically for crafting high-performing ad texts. This API empowers users with full control over the content and format of their ads, ensuring flexibility and customization.

What sets Ad Text Generation apart is its integration of **proven copywriting frameworks**, such as:

* **Before-After-Bridge**: Highlighting the transformation enabled by the product/service.
* **AIDA (Attention, Interest, Desire, Action)**: Guiding users from initial attention to final conversion.

These methodologies are extensively tested and continuously optimized to maximize conversions, ensuring the generated ad texts deliver top performance.

#### Seamless Multi-Format Support

Ad Text Generation is not limited to a single ad type. It supports **various ad formats**, offering tailored packages for platforms like:

* **Meta Dynamic Ad Creatives**
* **Google Performance Max Ads**

With this feature, marketers and developers can generate all necessary ad texts for these formats **within a single project**, eliminating the need for time-consuming manual copywriting.

#### Key Benefits

✅ Conversion-optimized ad texts powered by AdLLM Spark.\
✅ Full creative control over text content and format.\
✅ Proven frameworks designed for performance.\
✅ Multi-platform ad format support in a unified workflow.\
✅ Saves significant time and effort in the ad creation process.

With **Ad Text Generation API**, you can skip the hassle of writing copy from scratch and instantly get **ready-to-use, optimized ad texts** tailored to your campaign needs.

***

### Authorization

All endpoints requires the following headers 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`           |

#### Required Headers

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

***

## POST /api/v1/Text/Generation/Ads

This endpoint generates advertising text (ad copy) based on provided product details, target audience, and customization options. It is designed to create compelling ad texts tailored to specific marketing needs, supporting various text types, tones, languages, and emoji selections.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "processName": "Alo Yoga Ad Campaign",
  "productName": "Alo Yoga Clothing and Accessories",
  "productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
  "targetAudience": "Yoga Enthusiasts",
  "type": 1,
  "tone": "Professional",
  "outputLanguage": "es",
  "webSiteUrl": "https://www.aloyoga.com/",
  "cta": "Get Sales",
  "emojiSelection": 2,
  "customRequest": "Mention our patented technology; avoid using the word 'cheap'"
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="237">Parameter</th><th width="102">Type</th><th width="97">Required</th><th width="305">Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>GUID</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>GUID</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>processName</code></td><td><code>string</code></td><td>No</td><td>The name of the ad generation process. If empty, it defaults to <code>productName</code>. Max 1000 chars.</td><td><code>Alo Yoga Ad Campaign</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product being advertised. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Alo Yoga Clothing and Accessories</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Alo Yoga offers a wide range of yoga leggings...</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>No</td><td>The intended audience for the ad. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Yoga Enthusiasts</code></td></tr><tr><td><code>type</code></td><td><code>int</code></td><td>Yes</td><td>The type of ad text to generate. See AdTextType. Default: <code>1</code> (SharpTechnique).</td><td><code>1</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>No</td><td>The tone of the ad text. See AdTextTones. Max 1000 characters.</td><td><code>Professional</code></td></tr><tr><td><code>outputLanguage</code></td><td><code>string</code></td><td>Yes</td><td>The language of the generated ad text (e.g., <code>en</code>, <code>es</code>, <code>English</code>, <code>Spanish</code>). Max 100 chars.</td><td><code>es</code></td></tr><tr><td><code>webSiteUrl</code></td><td><code>string</code></td><td>No</td><td>The website URL related to the product. Max 2083 characters.</td><td><code>https://www.aloyoga.com/</code></td></tr><tr><td><code>cta</code></td><td><code>string</code></td><td>No</td><td>The call-to-action for the ad. Max 1000 chars. Can be fetched as <code>adGoal</code> or <code>cta</code> via <code>/ProductDescription endpoint</code>.</td><td><code>Get Sales</code></td></tr><tr><td><code>emojiSelection</code></td><td><code>int</code></td><td>Yes</td><td>Emoji usage in the ad text. See AdTextEmojiSelection. Default: <code>2</code> (ChosenByAi).</td><td><code>2</code></td></tr><tr><td><code>customRequest</code></td><td><code>string</code></td><td>No</td><td>Custom instructions for text generation (e.g., specific phrasing). Max 5000 characters.</td><td><code>Mention our patented technology; avoid 'cheap'</code></td></tr></tbody></table>

**Enum: AdTextType**

Refer to [AdTextType](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttype) for valid values (0-35). Examples:

* `1`: SharpTechnique (default)
* `2`: GateFramework
* `3`: LiftMethod

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

**Enum: AdTextEmojiSelection**

Refer to [AdTextEmojiSelection](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-7.-adtextemojiselection) for valid values:

* `0`: WithEmojis
* `1`: WithoutEmojis
* `2`: ChosenByAi (default)

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/Ads' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'processName="Alo Yoga Ad Campaign"' \
--form 'productName="Alo Yoga Clothing and Accessories"' \
--form 'productDescription="Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there'\''s something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle."' \
--form 'targetAudience="Yoga Enthusiasts"' \
--form 'type="1"' \
--form 'tone="Professional"' \
--form 'outputLanguage="es"' \
--form 'webSiteUrl="https://www.aloyoga.com/"' \
--form 'cta="Get Sales"' \
--form 'emojiSelection="2"' \
--form 'customRequest="Mention our patented technology; avoid using the word '\''cheap'\''"'
```

**HTTP Request**

```http
POST /api/v1/Text/Generation/Ads HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="processName"

Alo Yoga Ad Campaign
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Alo Yoga Clothing and Accessories
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"

Yoga Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="type"

1
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"

Professional
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="outputLanguage"

es
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="webSiteUrl"

https://www.aloyoga.com/
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cta"

Get Sales
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="emojiSelection"

2
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="customRequest"

Mention our patented technology; avoid using the word 'cheap'
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON object containing the generated ad texts and metadata:

```json
{
  "id": 102,
  "createdAt": "2025-03-06T04:31:56.2825674Z",
  "updatedAt": "2025-03-06T04:32:07.2719168Z",
  "adTexts": [
    {
      "id": 1145,
      "value": "Encuentra tu ajuste perfecto con Alo Yoga 🧘‍♂️",
      "favorited": false,
      "createdAt": "2025-03-06T04:32:07.2718587Z",
      "updatedAt": "2025-03-06T04:32:07.2718587Z",
      "conversionScore": "91",
      "type": 1
    },
    {
      "id": 1137,
      "value": "Envío gratis en Alo Yoga 🧘‍♀️",
      "favorited": false,
      "createdAt": "2025-03-06T04:32:07.2718576Z",
      "updatedAt": "2025-03-06T04:32:07.2718576Z",
      "conversionScore": "90",
      "type": 1
    }
  ]
}
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="299">Parameter</th><th width="109">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>int</code></td><td>The unique identifier of the ad text generation process.</td><td><code>102</code></td></tr><tr><td><code>createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was created (ISO 8601 format).</td><td><code>2025-03-06T04:31:56.2825674Z</code></td></tr><tr><td><code>updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was last updated (ISO 8601 format).</td><td><code>2025-03-06T04:32:07.2719168Z</code></td></tr><tr><td><code>adTexts</code></td><td><code>array</code></td><td>A list of generated ad text objects.</td><td>See below</td></tr><tr><td><code>adTexts[].id</code></td><td><code>int</code></td><td>The unique identifier of the ad text.</td><td><code>1145</code></td></tr><tr><td><code>adTexts[].value</code></td><td><code>string</code></td><td>The generated ad text content.</td><td><code>Encuentra tu ajuste perfecto con Alo Yoga 🧘‍♂️</code></td></tr><tr><td><code>adTexts[].favorited</code></td><td><code>bool</code></td><td>Indicates if the ad text has been marked as a favorite.</td><td><code>false</code></td></tr><tr><td><code>adTexts[].createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was created (ISO 8601 format).</td><td><code>2025-03-06T04:32:07.2718587Z</code></td></tr><tr><td><code>adTexts[].updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was last updated (ISO 8601 format).</td><td><code>2025-03-06T04:32:07.2718587Z</code></td></tr><tr><td><code>adTexts[].conversionScore</code></td><td><code>string</code></td><td>A score indicating the predicted effectiveness of the ad text (0-100).</td><td><code>91</code></td></tr><tr><td><code>adTexts[].type</code></td><td><code>int</code></td><td>The type of ad text, matching the request <code>type</code>. See AdTextType.</td><td><code>1</code></td></tr></tbody></table>

***

## PUT /api/v1/Text/Generation/Ads

This endpoint updates and regenerates advertising text (ad copy) for an existing ad text generation process identified by its `id`. It allows modification of product details, target audience, and customization options to produce updated ad texts tailored to specific marketing needs, supporting various text types, tones, languages, and emoji selections.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "id": 103,
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "processName": "Alo Yoga Ad Campaign",
  "productName": "Alo Yoga Clothing and Accessories",
  "productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
  "targetAudience": "Yoga Enthusiasts",
  "type": 1,
  "tone": "Friendly",
  "outputLanguage": "English",
  "webSiteUrl": "https://www.aloyoga.com/",
  "cta": "Get Sales",
  "emojiSelection": 2,
  "customRequest": "Mention our patented technology; avoid using the word 'cheap'"
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="232">Parameter</th><th width="118">Type</th><th width="82">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>int</code></td><td>Yes</td><td>The unique identifier of the ad text generation process to update.</td><td><code>103</code></td></tr><tr><td><code>applicationId</code></td><td><code>GUID</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>GUID</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>processName</code></td><td><code>string</code></td><td>No</td><td>The name of the ad generation process. If empty, defaults to <code>productName</code>. Max 1000 chars.</td><td><code>Alo Yoga Ad Campaign</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product being advertised. Max 1000 chars. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Alo Yoga Clothing and Accessories</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 chars. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Alo Yoga offers a wide range of yoga leggings...</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>No</td><td>The intended audience for the ad. Max 1000 chars. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Yoga Enthusiasts</code></td></tr><tr><td><code>type</code></td><td><code>int</code></td><td>Yes</td><td>The type of ad text to generate. See AdTextType. Default: <code>1</code> (SharpTechnique).</td><td><code>1</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>No</td><td>The tone of the ad text. See AdTextTones. Max 1000 chars.</td><td><code>Friendly</code></td></tr><tr><td><code>outputLanguage</code></td><td><code>string</code></td><td>Yes</td><td>The language of the generated ad text (e.g., <code>en</code>, <code>es</code>, <code>English</code>, <code>Spanish</code>). Max 100 chars.</td><td><code>English</code></td></tr><tr><td><code>webSiteUrl</code></td><td><code>string</code></td><td>No</td><td>The website URL related to the product. Max 2083 chars.</td><td><code>https://www.aloyoga.com/</code></td></tr><tr><td><code>cta</code></td><td><code>string</code></td><td>No</td><td>The call-to-action for the ad. Max 1000 chars. Can be fetched as <code>adGoal</code> or <code>cta</code> via <code>/ProductDescription endpoint</code>.</td><td><code>Get Sales</code></td></tr><tr><td><code>emojiSelection</code></td><td><code>int</code></td><td>Yes</td><td>Emoji usage in the ad text. See AdTextEmojiSelection. Default: <code>2</code> (ChosenByAi).</td><td><code>2</code></td></tr><tr><td><code>customRequest</code></td><td><code>string</code></td><td>No</td><td>Custom instructions for text generation (e.g., specific phrasing). Max 5000 chars.</td><td><code>Mention our patented technology; avoid 'cheap'</code></td></tr></tbody></table>

**Enum: AdTextType**

Refer to [AdTextType](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttype) for valid values (0-35). Examples:

* `1`: SharpTechnique (default)
* `2`: GateFramework
* `3`: LiftMethod

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

**Enum: AdTextEmojiSelection**

Refer to [AdTextEmojiSelection](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-7.-adtextemojiselection) for valid values:

* `0`: WithEmojis
* `1`: WithoutEmojis
* `2`: ChosenByAi (default)

#### Example Requests

**cURL**

```bash
curl --location --request PUT 'https://api.adcreative.ai/api/v1/Text/Generation/Ads' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'id="103"' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'processName="Alo Yoga Ad Campaign"' \
--form 'productName="Alo Yoga Clothing and Accessories"' \
--form 'productDescription="Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there'\''s something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle."' \
--form 'targetAudience="Yoga Enthusiasts"' \
--form 'type="1"' \
--form 'tone="Friendly"' \
--form 'outputLanguage="English"' \
--form 'webSiteUrl="https://www.aloyoga.com/"' \
--form 'cta="Get Sales"' \
--form 'emojiSelection="2"' \
--form 'customRequest="Mention our patented technology; avoid using the word '\''cheap'\''"'
```

**HTTP Request**

```http
PUT /api/v1/Text/Generation/Ads HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="id"

103
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="processName"

Alo Yoga Ad Campaign
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Alo Yoga Clothing and Accessories
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"

Yoga Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="type"

1
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"

Friendly
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="outputLanguage"

English
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="webSiteUrl"

https://www.aloyoga.com/
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cta"

Get Sales
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="emojiSelection"

2
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="customRequest"

Mention our patented technology; avoid using the word 'cheap'
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON object containing the updated ad texts and metadata:

```json
{
  "id": 103,
  "createdAt": "2025-03-06T10:29:59.635468Z",
  "updatedAt": "2025-03-06T10:30:40.7224539Z",
  "adTexts": [
    {
      "id": 1174,
      "value": "Free Shipping & Returns! Find Your Perfect Fit with Alo Yoga",
      "favorited": false,
      "createdAt": "2025-03-06T10:30:40.7224528Z",
      "updatedAt": "2025-03-06T10:30:40.7224528Z",
      "conversionScore": "96",
      "type": 1
    },
    {
      "id": 1166,
      "value": "Look & Feel Amazing! 🧘‍♀️",
      "favorited": false,
      "createdAt": "2025-03-06T10:30:40.722451Z",
      "updatedAt": "2025-03-06T10:30:40.722451Z",
      "conversionScore": "95",
      "type": 1
    }
  ]
}
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="299">Parameter</th><th width="114">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>int</code></td><td>The unique identifier of the ad text generation process.</td><td><code>103</code></td></tr><tr><td><code>createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was created (ISO 8601 format).</td><td><code>2025-03-06T10:29:59.635468Z</code></td></tr><tr><td><code>updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was last updated (ISO 8601 format).</td><td><code>2025-03-06T10:30:40.7224539Z</code></td></tr><tr><td><code>adTexts</code></td><td><code>array</code></td><td>A list of generated ad text objects.</td><td>See below</td></tr><tr><td><code>adTexts[].id</code></td><td><code>int</code></td><td>The unique identifier of the ad text.</td><td><code>1174</code></td></tr><tr><td><code>adTexts[].value</code></td><td><code>string</code></td><td>The generated ad text content.</td><td><code>Free Shipping &#x26; Returns! Find Your Perfect Fit with Alo Yoga</code></td></tr><tr><td><code>adTexts[].favorited</code></td><td><code>bool</code></td><td>Indicates if the ad text has been marked as a favorite.</td><td><code>false</code></td></tr><tr><td><code>adTexts[].createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was created (ISO 8601 format).</td><td><code>2025-03-06T10:30:40.7224528Z</code></td></tr><tr><td><code>adTexts[].updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was last updated (ISO 8601 format).</td><td><code>2025-03-06T10:30:40.7224528Z</code></td></tr><tr><td><code>adTexts[].conversionScore</code></td><td><code>string</code></td><td>A score indicating the predicted effectiveness of the ad text (0-100).</td><td><code>96</code></td></tr><tr><td><code>adTexts[].type</code></td><td><code>int</code></td><td>The type of ad text, matching the request <code>type</code>. See AdTextType.</td><td><code>1</code></td></tr></tbody></table>

***

## GET /api/v1/Text/Generation/UserAd

This endpoint retrieves a list of ad text generation processes for a specific user and optionally a specific process ID. It returns detailed information about the process, including generated ad texts, product details, and customization settings such as type, tone, and emoji selection.

### Request

The request is sent as a `GET` request with query parameters:

#### Request JSON Format

Since this is a `GET` request, there is no request body. However, the query parameters can be represented as a JSON object for clarity:

```json
{
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "adTextGeneratorProcessId": 103
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="288">Parameter</th><th width="106">Type</th><th width="90">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>userId</code></td><td><code>GUID</code></td><td>Yes</td><td>The unique identifier (GUID) of the user whose ad processes are retrieved.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>adTextGeneratorProcessId</code></td><td><code>int</code></td><td>No</td><td>The unique identifier of a specific ad text generation process to retrieve.</td><td><code>103</code></td></tr></tbody></table>

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/UserAd?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&adTextGeneratorProcessId=103' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9'
```

**HTTP Request**

```http
GET /api/v1/Text/Generation/UserAd?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&adTextGeneratorProcessId=103 HTTP/1.1
Host: api.adcreative.ai
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON array containing the ad text generation processes and their associated ad texts. Below is an example response (shortened for brevity):

```json
[
  {
    "id": 103,
    "type": 1,
    "productName": "Alo Yoga Clothing and Accessories",
    "productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
    "processName": "Alo Yoga Clothing and Accessories",
    "websiteUrl": "https://www.aloyoga.com/",
    "createdAt": "2025-03-06T10:29:59.635468Z",
    "updatedAt": "2025-03-06T10:30:40.722453Z",
    "cta": "Get Sales",
    "tone": "Friendly",
    "outputLanguage": "English",
    "targetAudience": "Yoga Enthusiasts",
    "emojiSelection": 2,
    "adTexts": [
      {
        "id": 1174,
        "value": "Free Shipping & Returns! Find Your Perfect Fit with Alo Yoga",
        "favorited": false,
        "createdAt": "2025-03-06T10:30:40.722452Z",
        "updatedAt": "2025-03-06T10:30:40.722452Z",
        "conversionScore": "96",
        "type": 1
      },
      {
        "id": 1166,
        "value": "Look & Feel Amazing! 🧘‍♀️",
        "favorited": false,
        "createdAt": "2025-03-06T10:30:40.722451Z",
        "updatedAt": "2025-03-06T10:30:40.722451Z",
        "conversionScore": "95",
        "type": 1
      }
    ]
  }
]
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th>Parameter</th><th width="126">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>int</code></td><td>The unique identifier of the ad text generation process.</td><td><code>103</code></td></tr><tr><td><code>type</code></td><td><code>int</code></td><td>The type of ad text generated. See AdTextType.</td><td><code>1</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>The name of the product being advertised.</td><td><code>Alo Yoga Clothing and Accessories</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>A detailed description of the product.</td><td><code>Alo Yoga offers a wide range of yoga leggings...</code></td></tr><tr><td><code>processName</code></td><td><code>string</code></td><td>The name of the ad generation process.</td><td><code>Alo Yoga Clothing and Accessories</code></td></tr><tr><td><code>websiteUrl</code></td><td><code>string</code></td><td>The website URL related to the product.</td><td><code>https://www.aloyoga.com/</code></td></tr><tr><td><code>createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was created (ISO 8601 format).</td><td><code>2025-03-06T10:29:59.635468Z</code></td></tr><tr><td><code>updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was last updated (ISO 8601 format).</td><td><code>2025-03-06T10:30:40.722453Z</code></td></tr><tr><td><code>cta</code></td><td><code>string</code></td><td>The call-to-action for the ad.</td><td><code>Get Sales</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>The tone of the generated ad text. See AdTextTones.</td><td><code>Friendly</code></td></tr><tr><td><code>outputLanguage</code></td><td><code>string</code></td><td>The language of the generated ad text.</td><td><code>English</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>The intended audience for the ad.</td><td><code>Yoga Enthusiasts</code></td></tr><tr><td><code>emojiSelection</code></td><td><code>int</code></td><td>Emoji usage in the ad text. See AdTextEmojiSelection.</td><td><code>2</code></td></tr><tr><td><code>adTexts</code></td><td><code>array</code></td><td>A list of generated ad text objects.</td><td>See below</td></tr><tr><td><code>adTexts[].id</code></td><td><code>int</code></td><td>The unique identifier of the ad text.</td><td><code>1174</code></td></tr><tr><td><code>adTexts[].value</code></td><td><code>string</code></td><td>The generated ad text content.</td><td><code>Free Shipping &#x26; Returns! Find Your Perfect Fit with Alo Yoga</code></td></tr><tr><td><code>adTexts[].favorited</code></td><td><code>bool</code></td><td>Indicates if the ad text has been marked as a favorite.</td><td><code>false</code></td></tr><tr><td><code>adTexts[].createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was created (ISO 8601 format).</td><td><code>2025-03-06T10:30:40.722452Z</code></td></tr><tr><td><code>adTexts[].updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was last updated (ISO 8601 format).</td><td><code>2025-03-06T10:30:40.722452Z</code></td></tr><tr><td><code>adTexts[].conversionScore</code></td><td><code>string</code></td><td>A score indicating the predicted effectiveness of the ad text (0-100).</td><td><code>96</code></td></tr><tr><td><code>adTexts[].type</code></td><td><code>int</code></td><td>The type of ad text, matching the process <code>type</code>. See AdTextType.</td><td><code>1</code></td></tr></tbody></table>

**Enum: AdTextType**

Refer to [AdTextType](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttype) for valid values (0-35). Examples:

* `1`: SharpTechnique (default)
* `2`: GateFramework
* `3`: LiftMethod

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

**Enum: AdTextEmojiSelection**

Refer to [AdTextEmojiSelection](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-7.-adtextemojiselection) for valid values:

* `0`: WithEmojis
* `1`: WithoutEmojis
* `2`: ChosenByAi (default)

***

## GET /api/v1/Text/Generation/ApplicationAllAds

This endpoint retrieves all ad text generation processes associated with a specific application ID. It returns detailed information about each process, including generated ad texts, product details, and customization settings such as type, tone, and emoji selection.

### Request

The request is sent as a `GET` request with a query parameter:

#### Request JSON Format

Since this is a `GET` request, there is no request body. However, the query parameter can be represented as a JSON object for clarity:

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="197">Parameter</th><th width="112">Type</th><th width="103">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>GUID</code></td><td>Yes</td><td>The unique identifier (GUID) of the application whose ad processes are retrieved.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr></tbody></table>

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/ApplicationAllAds?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9'
```

**HTTP Request**

```http
GET /api/v1/Text/Generation/ApplicationAllAds?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6 HTTP/1.1
Host: api.adcreative.ai
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON array containing the ad text generation processes and their associated ad texts. Below is a simplified example response with fewer `adTexts` entries to illustrate the structure:

```json
[
  {
    "id": 1,
    "type": 1,
    "productName": "Alo Yoga Clothing and Accessories",
    "productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
    "processName": "Alo Yoga Clothing and Accessories",
    "websiteUrl": "https://www.aloyoga.com/",
    "createdAt": "2025-01-23T04:04:15.296926Z",
    "updatedAt": "2025-01-23T04:05:53.269815Z",
    "cta": "Get Sales",
    "tone": "Friendly",
    "outputLanguage": "English",
    "targetAudience": "Yoga Enthusiasts",
    "emojiSelection": 2,
    "adTexts": [
      {
        "id": 19,
        "value": "Elevate Your Yoga Style",
        "favorited": false,
        "createdAt": "2025-01-23T04:05:53.269811Z",
        "updatedAt": "2025-01-23T04:05:53.269811Z",
        "conversionScore": "93",
        "type": 1
      },
      {
        "id": 26,
        "value": "Embrace Comfort & Style with Alo Yoga Apparel",
        "favorited": false,
        "createdAt": "2025-01-23T04:05:53.269812Z",
        "updatedAt": "2025-01-23T04:05:53.269812Z",
        "conversionScore": "93",
        "type": 1
      }
    ]
  },
  {
    "id": 2,
    "type": 1,
    "productName": "Alo Yoga Clothing and Accessories",
    "productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
    "processName": "Alo Yoga Clothing and Accessories",
    "websiteUrl": "https://www.aloyoga.com/",
    "createdAt": "2025-01-23T04:15:23.328589Z",
    "updatedAt": "2025-01-23T04:15:37.471426Z",
    "cta": "Get Sales",
    "tone": "Professional",
    "outputLanguage": "es",
    "targetAudience": "Yoga Enthusiasts",
    "emojiSelection": 2,
    "adTexts": [
      {
        "id": 41,
        "value": "Alo Yoga: Comodidad y estilo en cada pose",
        "favorited": false,
        "createdAt": "2025-01-23T04:15:37.471355Z",
        "updatedAt": "2025-01-23T04:15:37.471355Z",
        "conversionScore": "95",
        "type": 1
      },
      {
        "id": 45,
        "value": "Ropa de yoga Alo: Funcionalidad sin perder estilo",
        "favorited": false,
        "createdAt": "2025-01-23T04:15:37.471357Z",
        "updatedAt": "2025-01-23T04:15:37.471357Z",
        "conversionScore": "94",
        "type": 1
      }
    ]
  }
]
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="241">Parameter</th><th width="114">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>int</code></td><td>The unique identifier of the ad text generation process.</td><td><code>1</code></td></tr><tr><td><code>type</code></td><td><code>int</code></td><td>The type of ad text generated. See AdTextType.</td><td><code>1</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>The name of the product being advertised.</td><td><code>Alo Yoga Clothing and Accessories</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>A detailed description of the product.</td><td><code>Alo Yoga offers a wide range of yoga leggings...</code></td></tr><tr><td><code>processName</code></td><td><code>string</code></td><td>The name of the ad generation process.</td><td><code>Alo Yoga Clothing and Accessories</code></td></tr><tr><td><code>websiteUrl</code></td><td><code>string</code></td><td>The website URL related to the product.</td><td><code>https://www.aloyoga.com/</code></td></tr><tr><td><code>createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was created (ISO 8601 format).</td><td><code>2025-01-23T04:04:15.296926Z</code></td></tr><tr><td><code>updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the process was last updated (ISO 8601 format).</td><td><code>2025-01-23T04:05:53.269815Z</code></td></tr><tr><td><code>cta</code></td><td><code>string</code></td><td>The call-to-action for the ad.</td><td><code>Get Sales</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>The tone of the generated ad text. See AdTextTones.</td><td><code>Friendly</code></td></tr><tr><td><code>outputLanguage</code></td><td><code>string</code></td><td>The language of the generated ad text.</td><td><code>English</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>The intended audience for the ad.</td><td><code>Yoga Enthusiasts</code></td></tr><tr><td><code>emojiSelection</code></td><td><code>int</code></td><td>Emoji usage in the ad text. See AdTextEmojiSelection.</td><td><code>2</code></td></tr><tr><td><code>adTexts</code></td><td><code>array</code></td><td>A list of generated ad text objects.</td><td>See below</td></tr><tr><td><code>adTexts[].id</code></td><td><code>int</code></td><td>The unique identifier of the ad text.</td><td><code>19</code></td></tr><tr><td><code>adTexts[].value</code></td><td><code>string</code></td><td>The generated ad text content.</td><td><code>Elevate Your Yoga Style</code></td></tr><tr><td><code>adTexts[].favorited</code></td><td><code>bool</code></td><td>Indicates if the ad text has been marked as a favorite.</td><td><code>false</code></td></tr><tr><td><code>adTexts[].createdAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was created (ISO 8601 format).</td><td><code>2025-01-23T04:05:53.269811Z</code></td></tr><tr><td><code>adTexts[].updatedAt</code></td><td><code>string</code></td><td>The UTC timestamp when the ad text was last updated (ISO 8601 format).</td><td><code>2025-01-23T04:05:53.269811Z</code></td></tr><tr><td><code>adTexts[].conversionScore</code></td><td><code>string</code></td><td>A score indicating the predicted effectiveness of the ad text (0-100).</td><td><code>93</code></td></tr><tr><td><code>adTexts[].type</code></td><td><code>int</code></td><td>The type of ad text, matching the process <code>type</code>. See AdTextType.</td><td><code>1</code></td></tr></tbody></table>

**Enum: AdTextType**

Refer to [AdTextType](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttype) for valid values (0-35). Examples:

* `1`: SharpTechnique (default)
* `2`: GateFramework
* `3`: LiftMethod

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

**Enum: AdTextEmojiSelection**

Refer to [AdTextEmojiSelection](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-7.-adtextemojiselection) for valid values:

* `0`: WithEmojis
* `1`: WithoutEmojis
* `2`: ChosenByAi (default)

***

## GET /api/v1/Text/Generation/ProductDescription

This endpoint retrieves product-related information (e.g., product name, description, target audience) by scraping content from a specified website URL. It supports customization options such as preferred language and an advanced scraping mode.

### Request

The request is sent as a `GET` request with query parameters:

#### Request JSON Format

Since this is a `GET` request, there is no request body. However, the query parameters can be represented as a JSON object for clarity:

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "url": "https://www.caffettiera.ca/",
  "preferredLanguage": "en",
  "advanceMode": false
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="221">Parameter</th><th width="111">Type</th><th width="105">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>url</code></td><td><code>string</code></td><td>Yes</td><td>The website URL to scrape for product information. Must be a valid URL.</td><td><code>https://www.caffettiera.ca/</code></td></tr><tr><td><code>preferredLanguage</code></td><td><code>string</code></td><td>No</td><td>The preferred language for the extracted content (e.g., "en" for English). Defaults to "en".</td><td><code>en</code></td></tr><tr><td><code>advanceMode</code></td><td><code>bool</code></td><td>No</td><td>Indicates whether to use advanced mode to scrape website content, utilizing a scraping API with JavaScript rendering. Defaults to <code>false</code>.</td><td><code>false</code></td></tr></tbody></table>

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/ProductDescription?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&url=https%3A%2F%2Fwww.caffettiera.ca%2F&preferredLanguage=en&advanceMode=false' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9'
```

**HTTP Request**

```http
GET /api/v1/Text/Generation/ProductDescription?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&url=https://www.caffettiera.ca/&preferredLanguage=en&advanceMode=false HTTP/1.1
Host: api.adcreative.ai
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON object containing the extracted product-related information:

```json
{
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, serving authentic espresso Italiano. Our espresso is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialetti moka pots. Enjoy a cozy atmosphere where you can take a break from your day with our delicious offerings, including cappuccinos, focaccia sandwiches, and more. We pride ourselves on the quality of our coffee, adhering to the 5 ‘M’ rule for a perfect brew: The Blend, The Grind, The Machine, The Maintenance, and The Barista’s Hand.",
  "targetAudience": "Coffee enthusiasts",
  "adGoal": "Get Store Visits",
  "language": "English",
  "cta": "Visit us today!"
}
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="238">Parameter</th><th width="123">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>productName</code></td><td><code>string</code></td><td>The name of the product extracted from the website. May be null if not found.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>The detailed description of the product extracted from the website. May be null if not found.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>The target audience information extracted from the website. May be null if not found.</td><td><code>Coffee enthusiasts</code></td></tr><tr><td><code>adGoal</code></td><td><code>string</code></td><td>The advertising goal extracted from the website content. May be null if not found.</td><td><code>Get Store Visits</code></td></tr><tr><td><code>language</code></td><td><code>string</code></td><td>The language identified from the website content. May be null if not identified.</td><td><code>English</code></td></tr><tr><td><code>cta</code></td><td><code>string</code></td><td>The call-to-action (CTA) text extracted from the website content. May be null if not found.</td><td><code>Visit us today!</code></td></tr></tbody></table>

***

## POST /api/v1/Text/Generation/AdStrategies

This endpoint generates a list of advertising strategies based on provided product details, target audience, and advertising goals. Parameters such as `productName`, `productDescription`, `targetAudience`, and `adGoal` can be fetched from the response of the `GET /api/v1/Text/Generation/ProductDescription` endpoint.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
  "targetAudience": "Coffee Enthusiasts",
  "adGoal": "Get Store Visits"
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="235">Parameter</th><th width="120">Type</th><th width="93">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product being advertised. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>Yes</td><td>The intended audience for the ad. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Coffee Enthusiasts</code></td></tr><tr><td><code>adGoal</code></td><td><code>string</code></td><td>Yes</td><td>The advertising goal for the campaign. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code> as <code>adGoal</code> or <code>cta</code>.</td><td><code>Get Store Visits</code></td></tr><tr><td><code>currentStrategies</code></td><td><code>array</code></td><td>No</td><td>A list of current strategies already in use (optional). Each item is a string.</td><td><code>["Limited Time Offer", "Exclusive Discount"]</code></td></tr></tbody></table>

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/AdStrategies' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'targetAudience="Coffee Enthusiasts"' \
--form 'adGoal="Get Store Visits"'
```

**HTTP Request**

```http
POST /api/v1/Text/Generation/AdStrategies HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"

Coffee Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="adGoal"

Get Store Visits
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON array containing the generated ad strategies:

```json
[
  {
    "adStrategyShortName": "Limited Time Offer",
    "rationale": "A 'Limited Time Offer' creates urgency among coffee enthusiasts, encouraging them to visit the Italian-inspired bar for a unique espresso experience before the offer expires.",
    "fontAwesomeIcon": "fa-solid fa-clock"
  },
  {
    "adStrategyShortName": "Exclusive Discount",
    "rationale": "Offering an 'Exclusive Discount' incentivizes coffee lovers to experience the authentic Italian coffee and snacks at Caffettiera, driving increased foot traffic to the location.",
    "fontAwesomeIcon": "fa-solid fa-tag"
  },
  {
    "adStrategyShortName": "Buy One Get One Free",
    "rationale": "A 'Buy One Get One Free' offer on espresso drinks encourages coffee enthusiasts to visit Caffettiera with friends, boosting store visits and enhancing the social coffee experience.",
    "fontAwesomeIcon": "fa-solid fa-mug-hot"
  },
  {
    "adStrategyShortName": "Free Gift with Purchase",
    "rationale": "Providing a 'Free Gift with Purchase' such as an Italian snack motivates coffee enthusiasts to visit Caffettiera to enjoy both the coffee and a delightful treat, enhancing the overall experience.",
    "fontAwesomeIcon": "fa-solid fa-gift"
  }
]
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="251">Parameter</th><th width="112">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>adStrategyShortName</code></td><td><code>string</code></td><td>The short name of the advertising strategy.</td><td><code>Limited Time Offer</code></td></tr><tr><td><code>rationale</code></td><td><code>string</code></td><td>The rationale or reasoning behind the strategy.</td><td><code>A 'Limited Time Offer' creates urgency...</code></td></tr><tr><td><code>fontAwesomeIcon</code></td><td><code>string</code></td><td>The FontAwesome icon representing the strategy.</td><td><code>fa-solid fa-clock</code></td></tr></tbody></table>

***

## POST /api/v1/Text/Generation/AdCopies

This endpoint generates ad copies consisting of headlines, punchlines, and call-to-actions based on provided product details, strategy, tone, and other customization options. The `strategy` parameter can be fetched as `adStrategyShortName` from the `POST /api/v1/Text/Generation/AdStrategies` endpoint.&#x20;

Additionally, this endpoint serves as an alternative to provide diverse `headlines`, `punchlines`, and `actiontext` (as call-to-actions) for the following image generation endpoints before image creation:

* `POST /api/v1/Image/Generation/AdCreativesByKind`
* `POST /api/v1/Image/Editing/AdCreativesByTasks`

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
  "strategy": "Limited Time Offer",
  "cta": "Visit Us Today!",
  "outputLanguage": "en",
  "tone": "Professional",
  "targetAudience": "Coffee Enthusiasts",
  "isLongHeadline": true
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="236">Parameter</th><th width="123">Type</th><th width="96">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product being advertised. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>strategy</code></td><td><code>string</code></td><td>No</td><td>The advertising strategy to apply. Max 2000 characters. Can be fetched as <code>adStrategyShortName</code> from <code>/AdStrategies endpoint</code>.</td><td><code>Limited Time Offer</code></td></tr><tr><td><code>cta</code></td><td><code>string</code></td><td>Yes</td><td>The call-to-action text for the ad. Max 1000 characters. Can be fetched as <code>adGoal</code> or <code>cta</code> via <code>/ProductDescription endpoint</code>.</td><td><code>Visit Us Today!</code></td></tr><tr><td><code>outputLanguage</code></td><td><code>string</code></td><td>Yes</td><td>The language of the generated ad copy (e.g., "en", "English", "es", "Spanish"). Max 100 characters.</td><td><code>en</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>Yes</td><td>The tone of the ad copy (e.g., "Professional", "Informal", "Friendly"). Max 1000 characters. See AdTextTones.</td><td><code>Professional</code></td></tr><tr><td><code>targetAudience</code></td><td><code>string</code></td><td>Yes</td><td>The intended audience for the ad. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Coffee Enthusiasts</code></td></tr><tr><td><code>isLongHeadline</code></td><td><code>bool</code></td><td>Yes</td><td>Determines if headlines should be long and detailed (true) or short and concise (false, typically 13-17 words).</td><td><code>true</code></td></tr></tbody></table>

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/AdCopies' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'strategy="Limited Time Offer"' \
--form 'cta="Visit Us Today!"' \
--form 'outputLanguage="en"' \
--form 'tone="Professional"' \
--form 'targetAudience="Coffee Enthusiasts"' \
--form 'isLongHeadline="true"'
```

**HTTP Request**

```http
POST /api/v1/Text/Generation/AdCopies HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="strategy"

Limited Time Offer
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cta"

Visit Us Today!
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="outputLanguage"

en
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"

Professional
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"

Coffee Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="isLongHeadline"

true
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON object containing the generated ad copies, including headlines, punchlines, and call-to-actions. Below is a shortened example for brevity:

```json
{
  "headlines": [
    "Craving Authentic Italian Coffee in Montreal?",
    "Want a Taste of Italy in Every Sip?",
    "Seeking an Authentic Italian Coffee Experience in Montreal’s Golden Square Mile?",
    "Looking for Classic Bialetti-Brewed Coffee in a Cozy Italian Bar Setting?"
  ],
  "punchlines": [
    "Taste Italy in Every Sip",
    "Discover Espresso Perfection",
    "Indulge in 90's Italian Charm",
    "Experience La SanMarco Magic"
  ],
  "callToActions": [
    {
      "cta": "Taste Italy Today!",
      "fontAwesomeIcon": "fa-solid fa-coffee"
    },
    {
      "cta": "Sip Authentic Espresso!",
      "fontAwesomeIcon": "fa-solid fa-mug-hot"
    },
    {
      "cta": "Visit for Focaccia!",
      "fontAwesomeIcon": "fa-solid fa-bread-slice"
    },
    {
      "cta": "Discover Caffettiera!",
      "fontAwesomeIcon": "fa-solid fa-location-dot"
    }
  ]
}
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="355">Parameter</th><th width="126">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>headlines</code></td><td><code>array</code></td><td>A collection of generated headlines. Each item is a string.</td><td><code>"Craving Authentic Italian Coffee in Montreal?"</code></td></tr><tr><td><code>punchlines</code></td><td><code>array</code></td><td>A collection of generated punchlines. Each item is a string.</td><td><code>"Taste Italy in Every Sip"</code></td></tr><tr><td><code>callToActions</code></td><td><code>array</code></td><td>A collection of generated call-to-action objects.</td><td>See below</td></tr><tr><td><code>callToActions[].cta</code></td><td><code>string</code></td><td>The call-to-action text.</td><td><code>"Taste Italy Today!"</code></td></tr><tr><td><code>callToActions[].fontAwesomeIcon</code></td><td><code>string</code></td><td>The FontAwesome icon associated with the call-to-action.</td><td><code>"fa-solid fa-coffee"</code></td></tr></tbody></table>

***

## POST /api/v1/Text/Craft/ChangeSentiment

This endpoint changes the sentiment of a given text (e.g., a headline) based on provided product details and customization options like tone and language.&#x20;

It can be used to optimize outputs from the `POST /api/v1/Text/Generation/AdCopies` endpoint, refining headlines, punchlines, or call-to-actions to better suit the desired sentiment.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "headLine": "Craving true Italian espresso in Montreal's heart?",
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
  "tone": "Informal"
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th>Parameter</th><th width="138">Type</th><th width="103">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>headLine</code></td><td><code>string</code></td><td>Yes</td><td>The text (e.g., headline) to change sentiment for. Max 500 characters. Can be fetched from <code>/AdCopies endpoint</code> as <code>headlines</code>.</td><td><code>Craving true Italian espresso in Montreal's heart?</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>No</td><td>The desired tone of the text (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.</td><td><code>Informal</code></td></tr><tr><td><code>language</code></td><td><code>string</code></td><td>No</td><td>The language of the text (e.g., "en", "English"). Max 10 characters.</td><td><code>en</code></td></tr><tr><td><code>textLimit</code></td><td><code>int</code></td><td>No</td><td>The character limit for the output text. Must be between 1 and 1000. Defaults to 40.</td><td><code>40</code></td></tr></tbody></table>

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/ChangeSentiment' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'tone="Informal"'
```

**HTTP Request**

```http
POST /api/v1/Text/Craft/ChangeSentiment HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"

Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"

Informal
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a single string representing the text with its sentiment changed:

```json
"Espresso vibes in Montreal?"
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="147">Parameter</th><th width="146">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td>(response)</td><td><code>string</code></td><td>The text with its sentiment changed based on the provided inputs and tone.</td><td><code>"Espresso vibes in Montreal?"</code></td></tr></tbody></table>

***

## POST /api/v1/Text/Craft/MakeShorten

This endpoint shortens a given headline based on provided product details and customization options like tone, language, and a text limit.&#x20;

It can be used to optimize outputs from the `POST /api/v1/Text/Generation/AdCopies` endpoint, refining headlines to be more concise while preserving their core message.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "headLine": "Craving true Italian espresso in Montreal's heart?",
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="233">Parameter</th><th width="121">Type</th><th width="107">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>headLine</code></td><td><code>string</code></td><td>Yes</td><td>The headline to shorten. Max 500 characters. Can be fetched from <code>/AdCopies endpoint</code> as <code>headlines</code>.</td><td><code>Craving true Italian espresso in Montreal's heart?</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product. Max 1000 characters. Can be fetched via <code>/ProductDescription enpoint</code>.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>No</td><td>The desired tone of the text (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.</td><td><code>Informal</code></td></tr><tr><td><code>language</code></td><td><code>string</code></td><td>No</td><td>The language of the text (e.g., "en", "English"). Max 10 characters.</td><td><code>en</code></td></tr><tr><td><code>textLimit</code></td><td><code>int</code></td><td>No</td><td>The character limit for the shortened text. Must be between 1 and 1000. Defaults to 40.</td><td><code>40</code></td></tr></tbody></table>

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/MakeShorten' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."'
```

**HTTP Request**

```http
POST /api/v1/Text/Craft/MakeShorten HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"

Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a single string representing the shortened headline. (Note: The original input did not provide an example response, so an assumed example is included based on the endpoint’s purpose):

```json
"Craving Italian espresso?"
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="147">Parameter</th><th width="118">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td>(response)</td><td><code>string</code></td><td>The shortened version of the provided headline, adhering to the text limit.</td><td><code>"Craving Italian espresso?"</code></td></tr></tbody></table>

***

## POST /api/v1/Text/Craft/Translate

This endpoint translates a given text (e.g., a headline) into a specified target language based on provided product details and customization options.&#x20;

It can be used to translate outputs from the `POST /api/v1/Text/Generation/AdCopies` endpoint, such as headlines, punchlines, or call-to-actions, into different languages for broader reach.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "headLine": "Craving true Italian espresso in Montreal's heart?",
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
  "language": "Spanish"
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="235">Parameter</th><th width="110">Type</th><th width="91">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>headLine</code></td><td><code>string</code></td><td>Yes</td><td>The text (e.g., headline) to translate. Max 500 characters. Can be fetched from <code>/AdCopies endpoint</code> as <code>headlines</code>.</td><td><code>Craving true Italian espresso in Montreal's heart?</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>No</td><td>The desired tone of the text (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.</td><td><code>Informal</code></td></tr><tr><td><code>language</code></td><td><code>string</code></td><td>No</td><td>The target language for translation (e.g., "en", "English", "es", "Spanish"). Max 10 characters. If omitted, translation may not occur as expected.</td><td><code>Spanish</code></td></tr><tr><td><code>textLimit</code></td><td><code>int</code></td><td>No</td><td>The character limit for the translated text. Must be between 1 and 1000. Defaults to 40.</td><td><code>40</code></td></tr></tbody></table>

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/Translate' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'language="Spanish"'
```

**HTTP Request**

```http
POST /api/v1/Text/Craft/Translate HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"

Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="language"

Spanish
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a single string representing the translated text:

```json
"¿Deseas espresso italiano en Montreal?"
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="147">Parameter</th><th width="118">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td>(response)</td><td><code>string</code></td><td>The translated version of the provided text in the specified target language.</td><td><code>"¿Deseas espresso italiano en Montreal?"</code></td></tr></tbody></table>

***

## POST /api/v1/Text/Craft/CreateVariations

This endpoint creates multiple variations of a given headline based on provided product details and customization options like tone and language.&#x20;

It can be used to vary outputs from the `POST /api/v1/Text/Generation/AdCopies` endpoint, generating alternative headlines, punchlines, or call-to-actions for greater diversity.

### Request

The request is sent as `multipart/form-data` with the following parameters:

#### Request JSON Format

Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses `multipart/form-data`):

```json
{
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "headLine": "Craving true Italian espresso in Montreal's heart?",
  "productName": "Caffettiera",
  "productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."
}
```

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="236">Parameter</th><th width="118">Type</th><th width="111">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the application making the request. Must be a valid GUID string.</td><td><code>4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6</code></td></tr><tr><td><code>userId</code></td><td><code>Guid</code></td><td>Yes</td><td>The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.</td><td><code>2581c740-8e9d-4d63-96bc-5665bb9a646b</code></td></tr><tr><td><code>headLine</code></td><td><code>string</code></td><td>Yes</td><td>The headline to create variations for. Max 500 characters. Can be fetched from <code>/AdCopies endpoint</code> as <code>headlines</code>.</td><td><code>Craving true Italian espresso in Montreal's heart?</code></td></tr><tr><td><code>productName</code></td><td><code>string</code></td><td>Yes</td><td>The name of the product. Max 1000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera</code></td></tr><tr><td><code>productDescription</code></td><td><code>string</code></td><td>Yes</td><td>A detailed description of the product. Max 5000 characters. Can be fetched via <code>/ProductDescription endpoint</code>.</td><td><code>Caffettiera is a 90’s inspired Italian bar...</code></td></tr><tr><td><code>tone</code></td><td><code>string</code></td><td>No</td><td>The desired tone of the variations (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.</td><td><code>Informal</code></td></tr><tr><td><code>language</code></td><td><code>string</code></td><td>No</td><td>The language of the variations (e.g., "en", "English"). Max 10 characters.</td><td><code>en</code></td></tr><tr><td><code>textLimit</code></td><td><code>int</code></td><td>No</td><td>The character limit for each variation. Must be between 1 and 1000. Defaults to 40.</td><td><code>40</code></td></tr></tbody></table>

**Enum: AdTextTones**

Refer to [AdTextTones](https://api-docs.adcreative.ai/docs/getting-started/enums-and-descriptions#id-6.-adtexttones) for valid values. Examples:

* `Professional`
* `Informal`
* `Friendly`

#### Example Requests

**cURL**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/CreateVariations' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."'
```

**HTTP Request**

```http
POST /api/v1/Text/Craft/CreateVariations HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"

2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"

Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"

Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"

Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

### Response

#### Response JSON Format

A successful response returns a `200 OK` status with a JSON array containing multiple variations of the provided headline:

```json
[
  "Italian Espresso in Montreal!",
  "Savor Italy's Espresso Here!",
  "Authentic Italian Coffee Awaits!",
  "Discover Italian Espresso Bliss!",
  "Espresso Italiano in Montreal!"
]
```

#### Response Parameters

<table data-full-width="true"><thead><tr><th width="144">Parameter</th><th width="109">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td>(response)</td><td><code>array</code></td><td>A list of string variations of the provided headline, adhering to the text limit and tone.</td><td><code>"Italian Espresso in Montreal!"</code></td></tr></tbody></table>

***

## Common Error Responses in Ad Text Generation API

This section outlines the common error responses (excluding `200 OK`) that may occur across endpoints in the Ad Text Generation API feature. These errors include authorization issues (`401 Unauthorized`), client-side request issues (`400 Bad Request`), and server-side failures (`500 Internal Server Error`), along with validation errors. Error messages are categorized into `business:` and `engine:` keys:

* **`business:`** Represents errors originating from the business logic layer, providing user-friendly messages about why the request failed (e.g., missing resources, invalid inputs).
* **`engine:`** Represents errors from the engine layer, offering technical details for developers to debug underlying issues (e.g., exceptions, service failures).

These responses are designed to help customers understand issues and assist developers in troubleshooting integrations.

***

### Authorization Error Response

**HTTP Status Code:** `401 Unauthorized`

**Description:** This error occurs when the request lacks valid authentication credentials. Common causes include a missing or invalid API token (`x-api-key` or `x-api-secret`) or an `ApplicationId` that does not match any registered application in the token.

**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-d091dbc705803deaa77bd4d9abc17607-d1c93b4c70053719-00"
  }
}
```

**Guidance:** Ensure the `x-api-key` and `x-api-secret` headers are included and valid. Verify that the `ApplicationId` matches the one associated with your API credentials.

***

### Bad Request Error Response

**HTTP Status Code:** `400 Bad Request`

**Description:** This error indicates that the request is malformed, contains invalid data, or fails validation. It can stem from missing required fields, incorrect parameter formats, or business logic failures (e.g., no data found for the request). Below are several examples showcasing different scenarios.

#### Example 1: Validation Error (Single Field)

**Description:** Returned when a single parameter has an invalid value.

```json
{
  "errors": {
    "type": [
      "The value '99' is invalid."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-5e74736b3b7a4e64fb6fbc093c71bdda-c314cf7facb19565-00"
}
```

**Guidance:** Check the parameter named `type` and ensure it conforms to the expected format or range (e.g., an enum value).

#### Example 2: Validation Error (Multiple Fields)

**Description:** Returned when multiple required fields are missing or invalid.

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Type": [
      "The value '' is invalid."
    ],
    "ProductName": [
      "ProductName is required."
    ],
    "EmojiSelection": [
      "The value '' is invalid."
    ],
    "OutputLanguage": [
      "The OutputLanguage field is required."
    ],
    "ProductDescription": [
      "ProductDescription is required."
    ]
  },
  "traceId": "00-8dd517f6b559ac36115bc9711d7d7bb0-0071e9856eba9e87-00"
}
```

**Guidance:** Review the request body or parameters (e.g., `multipart/form-data`) and provide valid values for all required fields. Refer to the endpoint’s documentation for expected formats.

#### Example 3: Business and Engine Error (Resource Not Found)

**Description:** Returned when a specific resource cannot be found, with details from both business and engine layers.

```json
{
  "errors": {
    "engine: Generation/Ads": [
      "An unexpected error occurred while getting the ad text generation processes: No Ad Text Generation Process was not found for the AdTextGeneratorProcessId 104 or the User: 2581c740-8e9d-4d63-96bc-5665bb9a646b or the Application: "
    ],
    "business: Generation/UserAd": [
      "Bad request error occurred while getting Ad Text Generation Process for the AdTextGeneratorProcessId: 104 or the User: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 400,
  "detail": null,
  "instance": null,
  "extensions": {
    "traceId": "00-72523eede63262ad12f4ea0763b3b28f-bb0635ce1b353533-00"
  }
}
```

**Guidance:** Verify the `AdTextGeneratorProcessId`, `UserId`, and `ApplicationId`. The resource may not exist or the IDs may be incorrect.

#### Example 4: Business and Engine Error (Product Description Not Found)

**Description:** Returned when a product description cannot be retrieved for the given URL.

```json
{
  "errors": {
    "engine: Generation/ProductDescription": [
      "An unexpected error occurred while getting the product description: No product description was found for the URL: https://www.aloyoga/"
    ],
    "business: Generation/ProductDescription": [
      "Bad request error occurred while getting product description for the Application: d5eabbb8-c0f6-4640-94fd-3566edad499f and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b with the Url: https://www.aloyoga"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 400,
  "detail": null,
  "instance": null,
  "extensions": {
    "traceId": "00-5715acbbbe9bcdbb34aa3ada818d31bd-c9a07f0747128841-00"
  }
}
```

**Guidance:** Ensure the provided URL is valid and contains extractable product information. Check the `ApplicationId` and `UserId` as well.

#### Example 5: Business and Engine Error (Invalid URL Format)

**Description:** Returned when the URL format is invalid.

```json
{
  "errors": {
    "engine: Generation/ProductDescription": [
      "An unexpected error occurred while getting the product description: Invalid URL format. (Parameter 'url')"
    ],
    "business: Generation/ProductDescription": [
      "Bad request error occurred while getting product description for the Application: 4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6 and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b with the Url: ww.caffettier"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 400,
  "detail": null,
  "instance": null,
  "extensions": {
    "traceId": "00-cc89fdef1bc10c6cd8ecf0e3bdb0b5ce-5d0c5c161f603546-00"
  }
}
```

**Guidance:** Correct the URL format (e.g., include `https://` and a valid domain). The example `ww.caffettier` is malformed.

#### Example 6: Validation Error (Invalid GUIDs)

**Description:** Returned when `UserId` or `ApplicationId` are not valid GUIDs.

```json
{
  "errors": {
    "userId": [
      "The value '2581c740-8e9d-4d63-96bc-5665bb9a6' is not valid for UserId."
    ],
    "applicationId": [
      "The value 'c740-8e9d-4d63-96bc-5665bb9a646b' is not valid for ApplicationId."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-f96e34aa0aa1c80f1478bd591f317670-379ffdb0c0d6913a-00"
}
```

**Guidance:** Ensure `UserId` and `ApplicationId` are valid GUIDs (e.g., `2581c740-8e9d-4d63-96bc-5665bb9a646b`). Partial or malformed GUIDs are not accepted.

***

### Internal Server Error Response

**HTTP Status Code:** `500 Internal Server Error`

**Description:** This error indicates an unexpected server-side failure, such as an unhandled exception or service issue. It typically includes both `business:` and `engine:` messages for context and debugging.

**Response Body:**

```json
{
  "errors": {
    "business:": [
      "An unexpected error occurred while processing the request for the Application: 4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6 and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b for the Product: Caffettiera"
    ],
    "engine:": [
      "Internal service error: Unable to process request."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "An unexpected error occurred.",
  "status": 500,
  "detail": null,
  "instance": null,
  "extensions": {
    "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
  }
}
```

**Guidance:** This is a server-side issue. Retry the request later. If the problem persists, contact support with the `traceId` for assistance in diagnosing the issue.

***

#### General Notes on Error Responses

* **TraceId:** Each error includes a unique `traceId` in the `extensions` object (or top-level for some `400` responses) to help track and debug issues. Provide this ID when contacting support.
* **Business vs. Engine Errors:**
  * `business:` messages are user-facing, explaining what went wrong in a high-level context (e.g., "ProductName is required").
  * `engine:` messages are technical, aimed at developers, detailing the underlying issue (e.g., "Invalid URL format").
* **HTTP Standards:** The `type` field links to RFC 7231 or RFC 9110 sections for HTTP status code definitions, ensuring compliance with industry standards.
* **Validation Errors:** For `400 Bad Request`, validation errors list specific fields and issues. Check the endpoint’s documentation for required fields and formats.
* **Contact Support:** For persistent `500` errors or unclear `400`/`401` issues, use the `traceId` to report the problem to the support team.

***


# Product Photoshoot API

## 🛍️ Product Photoshoot API Introduction

Transform raw product images into polished ad creatives using AI-powered generation.

This API handles background removal, automatic product tagging, and creative generation through fine-tuned AI models. It allows for both predefined style presets and fully custom prompts, and returns studio-grade ad visuals from simple product photos.

***

### ⚙️ How It Works

The generation engine is powered by:

> **Fine-Tuned Stable Diffusion Inpainting**\
> A fine-tuned version of Stable Diffusion Inpainting, optimized for product placement use cases. It seamlessly embeds products into masked scene regions, maintaining realism and fidelity through domain-specific training.

***

### 🔁 Basic Flow

1. **Authenticate** via `/Authorization/GenerateJwtToken`
2. **Upload a product photo** using `/ProductGeneration/Recommendations`
   * Automatically extracts:\
     ✅ Product name & description\
     ✅ Background-removed image (`imageId`)\
     ✅ Prompt recommendations\
     ✅ Best-matching presetIds from `/ProductGeneration/PresetKeys`
3. **Start generation** via `/Image/ProductGeneration/AdCreative` using the `imageId`
4. **Track progress** via `/Image/ProductGeneration/CheckUserProgress`
   * Completion when: `progress = 100` and all 6 tasks return `renderState = 5`
   * Optional: Configure webhook via `/NotificationChannel` for real-time updates
5. **Download assets** via `/Image/ProductGeneration/Download`
   * Use `imageProductGeneratorProcessId` + `taskId`
   * Options:
     * `lowResolution = true/false`
     * `format = 0 (PNG) | 1 (JPEG) | 2 (PDF 1.6)`

***

### 🧠 Prompt Handling

**PromptObjectsString** (MAX 6 prompts):

```json
[
  {
    "tag": "custom",
    "prompt": "on a sleek black and blue geometric pattern background...",
    "nativeLanguagePrompt": null
  },
  {
    "preset": "white_pink_yellow_gradient_background_monochrome",
    "tag": "preset"
  },
  {
    "tag": "custom",
    "prompt": "custom style prompt",
    "nativeLanguagePrompt": null
  }
]
```

* `custom`: freeform style prompt
* `preset`: predefined styles from `/ProductGeneration/PresetKeys`

> Pass as a stringified array in the request body.

***

### 🎨 Presets

**GET** `/api/v1/Image/ProductGeneration/PresetKeys`

Retrieve predefined prompt styles categorized into groups like "monochrome", "studio", or "holiday".

```json
[
  {
    "id": "on_platform_natural_beige_background",
    "previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/on_platform_natural_beige_background.webp",
    "previewName": "On Platform Natural Beige Background",
    "promptText": "on a platform, in front of a natural beige background",
    "categories": [{ "name": "monochrome" }]
  },
  {
    "id": "thanksgiving_rustic_scene",
    "previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/thanksgiving_rustic_scene.webp",
    "previewName": "Thanksgiving Rustic Scene",
    "promptText": "product on rustic wood table with autumn leaves and warm lighting, thanksgiving style",
    "tags": ["holiday", "thanksgiving"]
  }
]
```

> Presets may include category-based or tag-based filters.\
> Some seasonal/holiday presets appear under "All" via internal tag logic.

***

### ⚠️ Common Error Scenarios

#### File too large

```json
Error while removing background: 
{
  "errors": [
    {
      "title": "File too large",
      "code": "file_too_large",
      "detail": "File exceeds limit of 22MB"
    }
  ]
}
```

→ Ensure images are in JPG or PNG format and are no larger than 22 MB.

***

#### Unknown foreground

```json
Error while removing background:
 {
  "errors": [
    {
      "title": "Could not identify foreground in image",
      "code": "unknown_foreground"
    }
  ]
}
```

→ Ensure your image has a well-defined object or product against a distinct background

***

### ✅ Tips for Best Results

* Foreground subject should be clear and well-lit
* Use simple backgrounds, avoid clutter
* Minimize shadows, reflections, and logos
* Ensure the product is fully visible, not cropped

***

#### 📋 GET /ProductGeneration/PresetKeys

Retrieve available preset configurations for product photo generation.

***

**Endpoint**

```
GET /api/v1/Image/ProductGeneration/PresetKeys
```

**Query Parameters**

<table data-full-width="true"><thead><tr><th width="165">Name</th><th width="150">Type</th><th width="213">Required</th><th>Description</th></tr></thead><tbody><tr><td>applicationId</td><td>GUID</td><td>Yes</td><td>The unique ID representing your application.</td></tr><tr><td>userId</td><td>GUID</td><td>Yes</td><td>The user ID under the application, used to scope presets.</td></tr></tbody></table>

***

**Example cURL Request**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/PresetKeys?applicationId=<your-application-id>&userId=<your-user-id>' \\
--header 'Accept: application/json' \\
--header 'x-api-key: <your-api-key>' \\
--header 'x-api-secret: <your-api-secret>'
```

***

**Example Successful Response**

```json
[
  {
    "id": "on_platform_natural_beige_background",
    "previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/on_platform_natural_beige_background.webp",
    "previewName": "On Platform Natural Beige Background",
    "promptText": "on a platform, in front of a natural beige background",
    "tags": [],
    "categories": [
      {
        "name": "monochrome"
      }
    ],
    "isOldPreset": false
  },
  {
    "id": "thanksgiving_rustic_scene",
    "previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/thanksgiving_rustic_scene.webp",
    "previewName": "Thanksgiving Rustic Scene",
    "promptText": "product on rustic wood table with autumn leaves and warm lighting, thanksgiving style",
    "tags": ["holiday", "thanksgiving"],
    "categories": [],
    "isOldPreset": false
  }
]
```

Here’s a quick example of how categories vs. tag-based filters work:

* The first preset (monochrome category) would appear under “All” with a category label.
* The second one is a holiday-specific preset (Thanksgiving) that doesn’t belong to a category but is surfaced based on name/prompt/tags.

***

**Preset Object Description**

<table data-full-width="true"><thead><tr><th width="295">Field</th><th width="205">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Identifier for the preset</td></tr><tr><td>previewImageUrl</td><td>string</td><td>URL of the preview image</td></tr><tr><td>previewName</td><td>string</td><td>Display name of the preset</td></tr><tr><td>promptText</td><td>string</td><td>Prompt text inserted into the generation prompt</td></tr><tr><td>tags</td><td>string[]</td><td>Optional tags used for internal filtering</td></tr><tr><td>categories</td><td>object[]</td><td>Categories for UI grouping and filtering</td></tr><tr><td>isOldPreset</td><td>boolean</td><td>Whether this preset is marked as legacy or outdated</td></tr></tbody></table>

***

**Notes**

* Presets are logical themes or scene styles for placing your product.
* Presets may be filtered and grouped by `categories`, such as `monochrome`, `studio`, etc.
* Seasonal or promotional presets (like `Thanksgiving`) are surfaced via internal tag or keyword search and may not appear in grouped views.
* The `All` section groups presets by `category.name`.
* Holiday-specific filters use tag-based logic and may not display category groupings.

***

### POST /ProductGeneration/Recommendations

Transform a single product image upload into a comprehensive generation setup.

#### Overview

This endpoint processes a product image and provides:

* Automatically extracted **product name & description**
* **Background-removed** version of the image, returning a unique `imageId` (you’ll use this in /ProductGeneration/AdCreative)
* **Prompt recommendations** based on the uploaded image
* A list of **recommended presetIds** from /ProductGeneration/PresetKeys that best match the uploaded image.

Useful for preparing everything needed for the `/ProductGeneration/AdCreative` step with a single call.

***

#### Endpoint

`POST /api/v1/Image/ProductGeneration/Recommendations`

***

#### Headers

| Name         | Required | Description           |
| ------------ | -------- | --------------------- |
| Content-Type | Yes      | `multipart/form-data` |
| Accept       | Yes      | `application/json`    |
| x-api-key    | Yes      | Your API Key          |
| x-api-secret | Yes      | Your API Secret       |

***

#### Form Data Parameters

| Name          | Type | Required | Description                                   |
| ------------- | ---- | -------- | --------------------------------------------- |
| applicationId | GUID | Yes      | ID of the application (API integrator)        |
| userId        | GUID | Yes      | ID of the user (or internal customer mapping) |
| productImage  | File | Yes      | JPG/PNG file up to 12MB                       |

***

#### Example Request (cURL)

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/Recommendations' \\
--header 'Content-Type: multipart/form-data' \\
--header 'Accept: application/json' \\
--header 'x-api-key: <your-api-key>' \\
--header 'x-api-secret: <your-api-secret>' \\
--form 'applicationId="<your-application-id>"' \\
--form 'userId="<your-user-id>"' \\
--form 'productImage=@"/path/to/image.png"'
```

***

#### Example Success Response

```json
{
  "productInfo": {
    "productName": "headphones",
    "productDescription": "Wireless over-ear headphones with noise-canceling features in vibrant red and black."
  },
  "backgroundRemovedImageAssetId": "ecc767e4-c107-4492-9826-89756e925425",
  "recommendedPrompts": [
    "on a sleek glass surface with a reflection of city skyscrapers...",
    "on a dynamic music waveform graphic...",
    "on a velvet cushion inside a luxurious music studio...",
    "on a vibrant graffiti wall in an urban alley..."
  ],
  "recommendedPresetIds": [
    "natural_beige_background",
    "white_background",
    "light_grey_background",
    "light_blue_background",
    "gray_shadowy_room_sunlight_streaming_studio",
    "gray_shadowy_room_sunlight_streaming_neutral"
  ]
}
```

***

#### Error Responses

**Missing Token or Invalid Token**

```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-6865a20820da1254cdd62ef5de9df71e-60781c154d97f7c6-00"
  }
}
```

**Missing or Invalid File Upload**

```json
{
  "errors": {
    "productImage": [
      "The productImage field is required.",
      "The request does not contain a file. Please make sure to upload the file."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-1342e34cfbba2b448dcaefe49e0b67d6-a3d4e02dd4b7f122-00"
}
```

***

#### 📸 /ProductGeneration/AdCreative Endpoint

**POST** `/api/v1/Image/ProductGeneration/AdCreative`

This endpoint is the core of the Product Photoshoot feature. It takes in a background-removed product image and returns multiple ad creatives generated using preset-based or custom prompts.

***

**🔐 Headers**

* `Content-Type`: multipart/form-data
* `Accept`: application/json
* `x-api-key`: *your api key*
* `x-api-secret`: *your api secret*

***

**🧾 Form Data Parameters**

<table data-full-width="true"><thead><tr><th>Name</th><th width="114">Required</th><th width="159">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td>✅</td><td>string</td><td>Application ID</td></tr><tr><td><code>userId</code></td><td>✅</td><td>string</td><td>User ID</td></tr><tr><td><code>renderKind</code></td><td>✅</td><td>int</td><td>One of: <code>0</code>, <code>1</code>, <code>2</code>, <code>4</code>, <code>8</code>, <code>16</code>, <code>31</code>, <code>32</code>, <code>64</code>, <code>128</code>, <code>256</code>, <code>512</code>, <code>992</code>, <code>1023</code></td></tr><tr><td><code>productImageAssetId</code></td><td>✅</td><td>string</td><td>Image Asset ID retrieved from <code>/ProductGeneration/Recommendations</code></td></tr><tr><td><code>PromptObjectsString</code></td><td>✅</td><td>string</td><td>JSON string containing an array of prompt objects (<code>preset</code> or <code>custom</code>)</td></tr><tr><td><code>productName</code></td><td>✅</td><td>string</td><td>Product name (recommended: extracted from <code>/Recommendations</code>)</td></tr><tr><td><code>productDescription</code></td><td>✅</td><td>string</td><td>Product description (recommended: extracted from <code>/Recommendations</code>)</td></tr><tr><td><code>DisableSafeMargin</code></td><td>❌</td><td>boolean</td><td>When true, returns images in strict 1200x628 instead of 1674x628 (see below)</td></tr><tr><td><code>UseSameStyleReferenceImage</code></td><td>❌</td><td>boolean</td><td>When true (default), uses the style, background and color palette from the preset image</td></tr></tbody></table>

***

**🖼️ Image Dimensions Behavior (DisableSafeMargin)**

By default, generated images are **1674x628**, offering **safe margins** to allow for design alignment (e.g. centering or left/right placement of products). This provides flexibility in use cases where further cropping or positioning is needed.

* `DisableSafeMargin = true`: returns **exact 1200x628** images (no margins)
* `DisableSafeMargin = false` or omitted: returns **1674x628** images with safe zones for alignment

***

**🎨 UseSameStyleReferenceImage**

When enabled (default), the preset’s background — represented by its previewImageUrl — is used as a visual style guide during generation. The AI blends the style and color palette from the preset image (e.g., white background, studio, floral themes) with the product image’s dominant colors to create a more personalized and brand-consistent Product Photoshoot.

For example, given a preset like:

```json
{
  "id": "white_background",
  "previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/white_background.webp",
  "previewName": "White Background",
  "promptText": ", in front of a white background",
  "categories": [ { "name": "monochrome" } ]
}
```

...if UseSameStyleReferenceImage is set to true, the AI will consider both the white background style and the uploaded product’s color scheme when composing the final output image.

***

**🧪 Example `curl` Request**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/AdCreative' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1' \
--header 'X-API-SECRET: b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1d4e7f0b3c2a5d9f6e1b7c4a8' \
--form 'applicationId="6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6"' \
--form 'userId="2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7"' \
--form 'renderKind="4"' \
--form 'productImageAssetId="d7f5c3b1-c029-4df5-8908-896ab0c1f24d"' \
--form 'PromptObjectsString="[{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"}]"' \
--form 'productName="vodka bottle"' \
--form 'productDescription="A clear glass bottle of vodka with blue and black text, set against a marble background with green leaves."' \
--form 'DisableSafeMargin="true"' \
--form 'UseSameStyleReferenceImage=""'
```

***

**✅ Example Response**

```json
{
  "messageType": "ImageProductGenerationProgress",
  "requestRenderState": 1,
  "applicationId": "6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6",
  "userId": "2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7",
  "imageRenderProcessId": "60a743a6-c761-4168-9288-40a729dd407e",
  "totalTaskCount": 6,
  "completedTaskCount": 0,
  "progress": 0,
  "tasks": {
    "e790c565-d56a-4e32-b00a-66be90cfcd43": 1,
    "5a172e34-dbb0-4459-90fe-f8c228fc367a": 1,
    "076804ca-0e0d-40ac-bbbb-3d4db390f05a": 1,
    "6c7a0759-96d7-4bf5-9109-526d9fce1c47": 1,
    "8610c0a9-2b3e-4934-ad02-26e786caf921": 1,
    "1f4f1c97-8215-4920-aceb-5f67dc9f38d7": 1
  },
  "renderType": 4,
  "isSuccessful": false,
  "errorMessage": ""
}
```

***

#### GET /ProductGeneration/Download

This endpoint is used to retrieve generated product visuals based on a `taskId` and `imageProductGeneratorProcessId`. It supports optional format and resolution flags.

***

**🔗 Endpoint**

```
GET /api/v1/Image/ProductGeneration/Download
```

**📥 Query Parameters**

<table data-full-width="true"><thead><tr><th width="301">Name</th><th width="112">Type</th><th width="123">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td>Guid</td><td>✅ Yes</td><td>Unique identifier of the application</td></tr><tr><td><code>taskId</code></td><td>Guid</td><td>✅ Yes</td><td>ID of the individual generation task</td></tr><tr><td><code>imageProductGeneratorProcessId</code></td><td>Guid</td><td>✅ Yes</td><td>ID of the overall product generation process</td></tr><tr><td><code>lowResolution</code></td><td>Boolean</td><td>❌ No</td><td>Default: <code>false</code>. Whether to return a low-resolution version.</td></tr><tr><td><code>format</code></td><td>Integer</td><td>❌ No</td><td>Format of the image: <code>0=PNG (default)</code>, <code>1=JPEG</code>, <code>2=PDF</code></td></tr></tbody></table>

***

**📤 Headers**

| Key             | Value                |
| --------------- | -------------------- |
| `Accept`        | `application/json`   |
| `x-api-key`     | `{your_api_key}`     |
| `x-api-secret`  | `{your_api_secret}`  |
| `Authorization` | `Bearer {jwt_token}` |

***

**📦 Example cURL Request**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/Download?applicationId={applicationId}&taskId={taskId}&imageProductGeneratorProcessId={imageProductGeneratorProcessId}&lowResolution=false&format=0' \\
--header 'Accept: application/json' \\
--header 'x-api-key: {your_api_key}' \\
--header 'x-api-secret: {your_api_secret}' \\
--header 'Authorization: Bearer {jwt_token}'
```

***

**✅ Response**

Returns the image as a file stream or downloadable content. If an error occurs, the following structure may be returned:

```json
{
  "errors": {
    "engine: ProductGeneration/Download": [
      "Image content not found."
    ],
    "business: ProductGeneration/Download": [
      "Not found error occurred while getting 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-599b17ae93900d22ce7df8169f3188f6-edcd222ed89634ed-00"
  }
}
```

***

**📝 Download Behavior**

<table data-header-hidden data-full-width="true"><thead><tr><th width="213"></th><th width="179"></th><th></th></tr></thead><tbody><tr><td><code>lowResolution</code></td><td><code>format</code></td><td>Description</td></tr><tr><td><code>false</code></td><td><code>0</code> (PNG)</td><td>Original high-res PNG is served as-is</td></tr><tr><td><code>false</code></td><td><code>1</code> (JPEG)</td><td>High-res PNG is converted to JPEG</td></tr><tr><td><code>true</code></td><td><code>1</code> (JPEG)</td><td>Thumbnail JPEG served as-is</td></tr><tr><td><code>true</code></td><td><code>0</code> (PNG)</td><td>Thumbnail JPEG is converted to PNG (increased file size due to full color)</td></tr><tr><td><code>false</code></td><td><code>2</code> (PDF)</td><td>Original is embedded into PDF 1.6</td></tr><tr><td><code>true</code></td><td><code>2</code> (PDF)</td><td>Thumbnail is embedded into PDF 1.6</td></tr></tbody></table>

***

**❗️Common Error Responses**

* **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-6865a20820da1254cdd62ef5de9df71e-60781c154d97f7c6-00"
    }
}
```

* **400 Bad Request – API Key Credits for Application does not exist**

```json
{
  "errors": {
    "engine: ProductGeneration/Download": [
      "Error decreasing Api Key Credits for Application e790c565-d56a-4e32-b00a-66be90cfcd43. ErrorMessage: API Key Credits for Application does not exist."
    ],
    "business: ProductGeneration/Download": [
      "Bad request error occurred while getting image content stream"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 400,
  "detail": null,
  "instance": null,
  "extensions": {
    "traceId": "00-5593df94b6415482f5d01c65f51de46f-9a0a8bfb206eae96-00"
  }
}
```

* **400 Bad Request – Validation Error**

```json
{
  "errors": {
    "imageProductGeneratorProcessId": [
      "The value '60a743a6-c761-4168-9288-40a729dd407e1' is not valid."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-ae0c64f2970933d69b2a159253a68fea-9e4a75471688ac32-00"
}
```

***

#### 🧠 Check User Progress

**Endpoint:**\
`GET /api/v1/Image/ProductGeneration/CheckUserProgress`

**Description:**\
Check the real-time rendering progress of Product Photoshoot generation requests for a specific user and render process.

**URL:**\
`https://api.adcreative.ai/api/v1/Image/ProductGeneration/CheckUserProgress?userId=2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7&imageProductGeneratorProcessId=60a743a6-c761-4168-9288-40a729dd407e`

**Authorization:**\
Bearer Token (Required)\
This request uses the Bearer Token

**Headers:**

```
Accept: application/json  
x-api-key: f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1  
x-api-secret: b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1d4e7f0b3c2a5d9f6e1b7c4a8
```

**Query Parameters:**

* `userId` (Required): The user ID of the requester
* `imageProductGeneratorProcessId` (Required): ID of the render process you wish to check

***

**🧪 Example Request**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/CheckUserProgress?userId=2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7&imageProductGeneratorProcessId=60a743a6-c761-4168-9288-40a729dd407e' \\
--header 'Accept: application/json' \\
--header 'x-api-key: f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1' \\
--header 'x-api-secret: b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1d4e7f0b3c2a5d9f6e1b7c4a8'
```

***

**✅ Example Response**

```json
[
  {
    "messageType": "ImageProductGenerationProgress",
    "requestRenderState": 5,
    "applicationId": "6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6",
    "userId": "2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7",
    "imageRenderProcessId": "60a743a6-c761-4168-9288-40a729dd407e",
    "totalTaskCount": 6,
    "completedTaskCount": 6,
    "progress": 100,
    "taskUrls": [
      {
        "taskId": "e790c565-d56a-4e32-b00a-66be90cfcd43",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/d177d546-3049-47c2-afdf-b320d38d63fc.png"
      },
      {
        "taskId": "5a172e34-dbb0-4459-90fe-f8c228fc367a",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/1a6cdca8-bf29-49e6-b2a6-2978e4739b05.png"
      },
      {
        "taskId": "076804ca-0e0d-40ac-bbbb-3d4db390f05a",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/fb75a55b-f95f-4e60-bfbd-18b984380dff.png"
      },
      {
        "taskId": "6c7a0759-96d7-4bf5-9109-526d9fce1c47",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/c794def5-1870-4699-8e4d-9381174b40bd.png"
      },
      {
        "taskId": "8610c0a9-2b3e-4934-ad02-26e786caf921",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/bd748e54-90ea-42d0-bee3-201fa9e11e49.png"
      },
      {
        "taskId": "1f4f1c97-8215-4920-aceb-5f67dc9f38d7",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/63bd51b3-3942-4ed7-b4ab-eb7cc41c83f1.png"
      }
    ],
    "renderType": 4,
    "isSuccessful": true,
    "errorMessage": ""
  }
]
```

***

**Notes:**

* `renderState` value `5` indicates that the generation task is completed.
* The `taskUrls` array contains publicly accessible image URLs for each generated product photo.
* Use the `taskId` values from this response when calling the `Download` endpoint.

***

#### 📊 GET /api/v1/Image/ProductGeneration/CheckApplicationAllProgresses

Checks the progress of all user-level image generations within a specific application.

**Endpoint**: `GET /api/v1/Image/ProductGeneration/CheckApplicationAllProgresses`\
**Auth**: Bearer Token

**🔐 Headers**

| Key          | Value                                       |
| ------------ | ------------------------------------------- |
| Accept       | application/json                            |
| x-api-key    | f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1            |
| x-api-secret | b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1... |

**📥 Params**

| Key           | Description |
| ------------- | ----------- |
| applicationId | Required    |

**🧪 Example Request**

```bash
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/CheckApplicationAllProgresses?applicationId=6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6' \\
--header 'Accept: application/json' \\
--header 'x-api-key: f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1' \\
--header 'x-api-secret: b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1d4e7f0b3c2a5d9f6e1b7c4a8'
```

**📤 Example Response**

```json
[
  {
    "messageType": "ImageProductGenerationProgress",
    "requestRenderState": 5,
    "applicationId": "6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6",
    "userId": "2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7",
    "imageRenderProcessId": "51b81216-fd1f-4af3-935f-c7e7f1a0b5af",
    "totalTaskCount": 6,
    "completedTaskCount": 6,
    "progress": 100,
    "taskUrls": [
      {
        "taskId": "7bf3c04a-c159-4e42-81fa-1bd5d2280372",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/6cc1319d-81b5-427e-8f43-238f326b9381.png"
      },
      {
        "taskId": "9855e1fc-d859-4307-b9d3-dac0f5951227",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/99071d6b-946c-4815-9eca-c508373d129b.png"
      },
      {
        "taskId": "9033d6b8-ac39-4c3b-a326-9e61fdf98b34",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/d9f085fb-8884-4e6c-879f-1b647e5091b7.png"
      },
      {
        "taskId": "d0417a50-a42f-48cc-a23c-0d4d00d277c5",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/465f9731-fbfd-4301-8a27-b7bb919e30eb.png"
      },
      {
        "taskId": "301eb9f8-ac82-4e53-ab49-9dcb66729383",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/9e52d180-e067-4220-b7f9-ba33c7d3e2af.png"
      },
      {
        "taskId": "b7a45b59-e022-47b0-a527-7dd2ba0d3ba2",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/36196d3f-bd10-4410-bf00-32fbe298bc25.png"
      }
    ],
    "renderType": 4,
    "isSuccessful": true,
    "errorMessage": ""
  },
  {
    "messageType": "ImageProductGenerationProgress",
    "requestRenderState": 5,
    "applicationId": "6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6",
    "userId": "2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7",
    "imageRenderProcessId": "e1fafe2b-40dd-4448-8c12-13a4738185b0",
    "totalTaskCount": 6,
    "completedTaskCount": 6,
    "progress": 100,
    "taskUrls": [
      {
        "taskId": "a033cadf-4d15-49fd-bfa2-51cc5956a6f7",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/ffd01f2b-9b3a-4d31-8b44-92594c7a87aa.png"
      },
      {
        "taskId": "c3233c50-88e5-46bf-93b0-ebe839480360",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/b84468f5-c21a-49d2-83ae-1edcb65427b9.png"
      },
      {
        "taskId": "f1266bfb-9c01-4867-964b-de0a2ee57a64",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/33b856a6-0c04-4c88-8da8-6bbac963e37a.png"
      },
      {
        "taskId": "6decfe70-1713-4966-8580-68337d3278a7",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/e1a213ac-2a1a-484a-a529-658e9472a266.png"
      },
      {
        "taskId": "42e2406e-34ee-4f1b-9550-59de81bca30f",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/fdbcc767-0a34-4931-8257-7e7472fe2ba8.png"
      },
      {
        "taskId": "ac96db4e-b066-41b8-b86e-579346d66d73",
        "renderState": 5,
        "publicImageUrl": "https://storage.googleapis.com/adcreative-bucket/images/ai-product-images/45c5ee7a-0861-402d-bd96-6a3394d3a65a.png"
      }
    ],
    "renderType": 4,
    "isSuccessful": true,
    "errorMessage": ""
  }
]
```

> This endpoint is ideal for applications managing multiple users and monitoring all ongoing generation jobs across the system.


# Creative Scoring API (Soon)


# Fine-tune Generation API (Soon)


# Editor

GitBook has a powerful block-based editor that allows you to seamlessly create, update, and enhance your content.

<figure><img src="https://gitbookio.github.io/onboarding-template-images/editor-hero.png" alt=""><figcaption></figcaption></figure>

### Writing content

GitBook offers a range of block types for you to add to your content inline — from simple text and tables, to code blocks and more. These elements will make your pages more useful to readers, and offer extra information and context.

Either start typing below, or press `/` to see a list of the blocks you can insert into your page.

### Add a new block

{% stepper %}
{% step %}

### Open the insert block menu

Press `/` on your keyboard to open the insert block menu.
{% endstep %}

{% step %}

### Search for the block you need&#x20;

Try searching for “Stepper”, for exampe, to insert the stepper block.
{% endstep %}

{% step %}

### Insert and edit your block

Click or press Enter to insert your block. From here, you’ll be able to edit it as needed.
{% endstep %}
{% endstepper %}


# Markdown

GitBook supports many different types of content, and is backed by Markdown — meaning you can copy and paste any existing Markdown files directly into the editor!

<figure><img src="https://gitbookio.github.io/onboarding-template-images/markdown-hero.png" alt=""><figcaption></figcaption></figure>

Feel free to test it out and copy the Markdown below by hovering over the code block in the upper right, and pasting into a new line underneath.

```markdown
# Heading

This is some paragraph text, with a [link](https://docs.gitbook.com) to our docs. 

## Heading 2
- Point 1
- Point 2
- Point 3
```

{% hint style="info" %}
If you have multiple files, GitBook makes it easy to import full repositories too — allowing you to keep your GitBook content in sync.
{% endhint %}


# Images & media

GitBook allows you to add images and media easily to your docs. Simply drag a file into the editor, or use the file manager in the upper right corner to upload multiple images at once.

<figure><img src="https://gitbookio.github.io/onboarding-template-images/images-hero.png" alt=""><figcaption><p>Add alt text and captions to your images</p></figcaption></figure>

{% hint style="info" %}
You can also add images simply by copying and pasting them directly into the editor — and GitBook will automatically add it to your file manager.
{% endhint %}


# Interactive blocks

In addition to the default Markdown you can write, GitBook has a number of out-of-the-box interactive blocks you can use. You can find interactive blocks by pressing `/` from within the editor.

<figure><img src="https://gitbookio.github.io/onboarding-template-images/interactive-hero.png" alt=""><figcaption></figcaption></figure>

### Tabs

{% tabs %}
{% tab title="First tab" %}
Each tab is like a mini page — it can contain multiple other blocks, of any type. So you can add code blocks, images, integration blocks and more to individual tabs in the same tab block.
{% endtab %}

{% tab title="Second tab" %}
Add images, embedded content, code blocks, and more.

```javascript
const handleFetchEvent = async (request, context) => {
    return new Response({message: "Hello World"});
};
```

{% endtab %}
{% endtabs %}

### Expandable sections

<details>

<summary>Click me to expand</summary>

Expandable blocks are helpful in condensing what could otherwise be a lengthy paragraph. They are also great in step-by-step guides and FAQs.

</details>

### Drawings

<img alt="" class="gitbook-drawing">

### Embedded content

{% embed url="<https://www.youtube.com/watch?v=YILlrDYzAm4>" %}

{% hint style="info" %}
GitBook supports thousands of embedded websites out-of-the-box, simply by pasting their links. Feel free to check out which ones[ are supported natively](https://iframely.com).
{% endhint %}


# OpenAPI

You can sync GitBook pages with an OpenAPI or Swagger file or a URL to include auto-generated API methods in your documentation.

### OpenAPI block

GitBook's OpenAPI block is powered by [Scalar](https://scalar.com/), so you can test your APIs directly from your docs.

{% openapi src="<https://petstore3.swagger.io/api/v3/openapi.json>" path="/pet" method="post" %}
<https://petstore3.swagger.io/api/v3/openapi.json>
{% endopenapi %}


# Integrations

GitBook integrations allow you to connect your GitBook spaces to some of your favorite platforms and services. You can install integrations into your GitBook page from the *Integrations* menu in the top left.

<figure><img src="https://gitbookio.github.io/onboarding-template-images/integrations-hero.png" alt=""><figcaption></figcaption></figure>

### Types of integrations

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Analytics</strong></td><td>Track analytics from your docs</td><td><a href="https://www.gitbook.com/integrations#analytics">https://www.gitbook.com/integrations#analytics</a></td><td></td><td></td></tr><tr><td><strong>Support</strong></td><td>Add support widgets to your docs</td><td><a href="https://www.gitbook.com/integrations#support">https://www.gitbook.com/integrations#support</a></td><td></td><td></td></tr><tr><td><strong>Interactive</strong></td><td>Add extra functionality to your docs</td><td><a href="https://www.gitbook.com/integrations#interactive">https://www.gitbook.com/integrations#interactive</a></td><td></td><td></td></tr><tr><td><strong>Visitor Authentication</strong></td><td>Protect your docs and require sign-in</td><td><a href="https://www.gitbook.com/integrations#visitor-authentication">https://www.gitbook.com/integrations#visitor-authentication</a></td><td></td><td></td></tr></tbody></table>


