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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.adcreative.ai/docs/getting-started/quickstart/core-capabilities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.