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:

Header

Description

Example Value

Authorization

Bearer token for authentication

Bearer <YOUR_BEARER_TOKEN>

x-api-key

API Key for the application

<YOUR_API_KEY>

x-api-secret

Secret Key for the application

<YOUR_API_SECRET>

Content-Type

Specifies the data format

multipart/form-data

Expected response format

application/json

Parameters

Parameter

Type

Description

Required

Notes

applicationId

Guid

Application ID initiating the request.

Yes

Must be a non-empty GUID.

userId

Guid

User ID for whom the image generation is being performed.

Yes

Must be a non-empty GUID.

renderKind

Enum

Render kind (e.g., Post, Story). Specifies the type of render. Accepted values are defined in the RenderKind enum.

Yes

See RenderKind values in "Enums and Descriptions" page.

imageStyle

Enum

Style of the generated image (e.g., Photorealistic, CustomWithText. Default: 3 "Photorealistic")

Yes

Default: Photorealistic. See ImageStyle values in "Enums and Descriptions" page.

userPrompt

String

Description of the desired stock image.

Yes

Max length: 1000 characters.

customStyleText

String

Text description of the desired custom style.

Conditional

Required if imageStyle is CustomWithText. Max length: 1000 characters.

customStyleImage

File

Image file to transfer its style from.

Conditional

Required if imageStyle is CustomWithImage.

loraParams

String

Lora parameters as key-value pairs for additional AI parameters.

Example format: GUID1:float,GUID2:float

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

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

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

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

{
    "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

{
    "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

{
    "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

{
    "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

Name

Type

Required

Description

userId

Guid

Yes

The unique identifier of the user whose stock image generation progress is being queried.

imageStockGenerator

ProcessId

Guid

The unique identifier of a specific stock image generation process for the user.

Request Examples

CURL Example

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

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)

[
  {
    "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)

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

{
    "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

Name

Type

Required

Description

applicationId

Guid

Yes

The unique identifier of the application for which the stock image generation progress is being queried.

Request Examples

CURL Example

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

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)

[
  {
      "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)

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

{
    "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

Parameter

Type

Required

Description

Example Value

applicationId

Guid

Yes

ID of the application making the request

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6

taskId

Guid

Yes

Unique identifier for the specific task

165ce0c4-27a4-4317-a388-3c4064cf8b17

imageStockGenerator

ProcessId

Guid

Yes

ID of the stock generation process

2c3a9038-a7c8-4a8a-8821-a66dc433c3dd

lowResolution

bool

Indicates whether the image is in low resolution

true

Example Request

cURL Command:

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:

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

{
    "$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:

{
    "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

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

PreviousScan My Website API NextAd Text Generation API

Last updated 1 year ago