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
Accept
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.
No
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());
{
"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.
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());
{
"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"
}
}
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());
{
"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.
HTTP Status Code: 200 OKResponse Type: FileStreamDetails: The requested image file stream will be directly downloaded.
Authorization Error Response
HTTP Status Code: 401 UnauthorizedResponse 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 RequestResponse 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 FoundResponse 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.
