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

***