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

***


---

# 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/features/stock-image-generation-api.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.