Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This API expands a given user input into a detailed prompt description suitable for creative tasks such as designing posters, creating advertisements, and more.
API Endpoint
POST https://api.genaifactory.ai/v1/expand_promptHeaders
formacloud-api-key
string
Yes
API key for authentication
Content-Type
string
Yes
Set to application/json
Request Body
user_input
string
Yes
The user’s input text that needs to be expanded
Example Request
curl --location 'http://localhost:3300/v1/expand_prompt' \
--header 'formacloud-api-key: abc123' \
--header 'Content-Type: application/json' \
--data '{
"user_input": "Help me create a poster of shoes"
}'Response
A JSON object containing the expanded prompt description.
expanded_prompt
string
Detailed prompt text generated by the API
Example Response
{
"expanded_prompt": "Create a poster that showcases a vibrant collection of shoes displayed in a dynamic arrangement, drawing the viewer's eye across the design. The layout features a central focus on various styles, such as sneakers, sandals, and boots, placed at different angles to create depth and visual interest. \n\nThe poster should feature stunning photography of the shoes, accentuated by texture close-ups and playful backgrounds that highlight their unique designs. \n\nThe color scheme consists of bright, energetic hues like electric blue, neon green, and fiery orange, complemented by contrasting soft pastels for a modern, youthful vibe. \n\nText elements include a bold title at the top, reading \"Step into Style!\" in an eye-catching sans-serif font, followed by catchy taglines beneath each shoe style, conveying their distinct appeal. \n\nSupporting graphics include playful geometric patterns and subtle shoe footprints weaving around the footwear, adding a sense of movement and energy. \n\nThe mood and atmosphere evoke excitement and a sense of adventure, inviting viewers to explore new fashion possibilities. A prominent call to action at the bottom urges, \"Find Your Perfect Pair Today!\" encouraging immediate engagement."
}The Retrieve credit endpoint allows you to check the total amount of credit available and how much has been used. This is useful for monitoring your API usage and ensuring you have sufficient credit for future tasks.
API Endpoint
To retrieve your credit information, send a GET request to the following URL:
GET https://api.genaifactory.ai/v1/credit
Headers
Ensure that your request includes the following header:
Response Body
The response will provide details about your credit usage:
Example Request
Example Response
Success Response (Status Code 200)
Failure Response (Status Code 4XX)
This API extracts information from a given image and user input to generate a detailed prompt description for creating a poster. Note: This API typically requires approximately 15 seconds to process and return a response.
API Endpoint
Headers
Request Body
Note: referring_image and referring_image_url cannot be provided together.
Example Request
Response
Returns a JSON object containing the generated detailed prompt description.
Example Response
Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
Name
Type
Required
Description
total_credit
number
Yes
The total amount of credit allocated for tasks.
used_credit
number
Yes
The amount of credit used by tasks.
curl -G 'https://api.genaifactory.ai/v1/credit' \
-H 'formacloud-api-key: abc123'{
"total_credit": "1.00",
"used_credit": "0.11"
}{
"error": "Invalid API key",
}POST https://api.genaifactory.ai/v1/image_to_promptformacloud-api-key
string
Yes
API key for authentication
user_input
string
No
The user’s input text describing requirements (max 200 characters)
referring_image
file
No
The image file to be used for inspiration
referring_image_url
string
No
URL of the image to be used for inspiration
curl --location 'https://api.genaifactory.ai/v1/image_to_prompt' \
--header 'formacloud-api-key: abc123' \
--form 'user_input="Help me extract the contents of the entire image"'\
--form 'referring_image_url="https://example.com/inspiration_image.jpg"'image_to_prompt
string
Detailed prompt text generated by the API
{
"image_to_prompt": "In this picture, you can see a winding \"river\" made of white rice grains, with a black background forming the outline of the river. In the center of the river, there is a lonely black figure walking on the river, giving people a feeling of walking alone, thinking or reminiscing. At the bottom right of the picture, there are Chinese words: \"The long river of time always has some people worth remembering\", and the English translation: "THERE ARE ALWAYS SOME PEOPLE WORTH REMEMBERING". \n\nThe content of this picture conveys a feeling of time passing, nostalgia and gratitude. The overall color tone is mainly white and black, simple but meaningful. The whole picture indicates that people move forward in the long river of time. Although the years are ruthless, there are always some people who are worth remembering and remembering."
}Moonveil redefines text-to-image generation with its proprietary model, offering unparalleled 100% text accuracy in outputs. Our platform caters to all users: casual creators can export PNGs, while professionals enjoy SVG options for easy editing. With a powerful API for enterprise integration and AI-driven free-form input alongside customizable parameters, Moonveil combines precision with user-friendliness. Whether you're a hobbyist or a business professional, Moonveil is your go-to solution for turning text into stunning, accurate visuals.
Added the task_types parameter to retrieve image history API.
Added the time related fields info to get image generation API.
Fixed error header in image to prompt doc.
v1/image_history
Added the Redraw Image API to allow redrawing original image.
Added the Export Image as SVG API to allow exporting a task's output image as an SVG.
Added the estimate_image_time parameter to the response schema. This parameter provides an estimated execution time (in seconds) for the task based on recent task performance data.
Added a note to the "Image to Prompt" API documentation indicating that this API typically requires approximately 15 seconds to return a response.
Added width and height parameters for Create Images API.
Added Retrieve Recharge History API.
Supported 16 image sytles. https://moonveil.ai/app/styles
Enabled the "Create Image without Text" feature in the Create Images API.
Endpoint
GET https://api.genaifactory.ai/v1/assets/{asset_id}Headers
app-id
string
Yes
Must be "flickbloom"
authorization
string
Yes
Bearer token for user authentication
Path Parameter
asset_id
int
Yes
ID of the asset
Example Request
curl --location 'https://api.genaifactory.ai/v1/assets/1' \
--header 'app-id: flickbloom' \
--header 'authorization: Bearer YOUR_JWT_TOKEN'Response
{
"id": 123,
"url": "https://.../my_file.pdf",
"description": "My uploaded file",
"file_type": "pdf"
}Error Responses
400 Bad Request
{ "error": "Invalid asset ID: abc" }404 Not Found
{ "error": "Asset not found" }401 Unauthorized
{ "error": "Authentication required or token invalid" }Endpoint
DELETE https://api.genaifactory.ai/v1/conversation_history/{session_id}Headers
formacloud-api-key
string
Yes
API key for authentication
Path Parameters
session_id
string
Yes
The unique session identifier for the conversation to be deactivated.
Example Request
curl --location --request DELETE 'https://api.genaifactory.ai/v1/conversation_history/123e4567-e89b-12d3-a456-426614174000' \
--header 'formacloud-api-key: abc123'Responses
✅ Success Response (200 OK)
If the conversation is successfully deactivated:
{
"message": "Conversation with session_id 123e4567-e89b-12d3-a456-426614174000 has been deactivated"
}❌ Error Response (404 Not Found)
If the provided session_id does not exist:
{
"error": "No steps of this history 123e4567-e89b-12d3-a456-426614174000 found"
}The redraw_image endpoint allows users to modify or recreate a given image using a specified mask and text prompt. This API is ideal for use cases such as creating customized visuals, refining designs, or replacing specific parts of an image while retaining its original structure.
To redraw an image, send a POST request to the following URL:
POST https://api.genaifactory.ai/v1/redraw_image
The request body should be sent as form-data and include the following fields:
Note: Either the file or the url must be provided for both the original image and the mask but not both simultaneously.
Asynchronous Response (Status Code 202)
Failure Response (Status Code 4XX or 5XX)
Using curl Command
Asynchronous Response
Failure Response
Endpoint
Headers
Path Parameter
Example Request
Response (Soft Delete)
Error Responses
400 Bad Request – Invalid asset ID
404 Not Found – Asset not found
401 Unauthorized – Invalid user token
Endpoint
Headers
Path Parameter
Request Body
Example Request
Response
Error Responses
400 Bad Request – Invalid asset ID or missing description
404 Not Found – Asset not found
401 Unauthorized – Invalid user token
formacloud-api-key
string
Yes
API key required for authenticating your request.
user_input
string
No
A brief textual description (max 200 characters) for guiding the image redrawing process.
original_image
file
No
The original image file to be redrawn. Must not be provided with original_image_url.
original_image_url
string
No
URL of the original image to be redrawn. Must not be provided with original_image.
mask_image
file
No
Mask file specifying areas to be redrawn. Must not be provided with mask_image_url.
mask_image_url
string
No
URL of the mask file specifying areas to be redrawn. Must not be provided with mask_image.
task_id
string
Yes
The ID of the task created for redrawing the image.
tasks_ahead_count
int
Yes
Number of tasks ahead in the queue when this task is created.
estimate_image_time
int
Yes
Estimated time (in seconds) to complete the task based on recent data.
error
string
Yes
A descriptive error message indicating what went wrong with the request.
curl --location 'https://api.genaifactory.ai/v1/redraw_image' \
--header 'formacloud-api-key: abc' \
--form 'user_input="movie poster says \"FORMA CLOUD\""' \
--form 'original_image_url="https://replicate.delivery/pbxt/M0gpKVE9wmEtOQFNDOpwz1uGs0u6nK2NcE85IihwlN0ZEnMF/kill-bill-poster.jpg"' \
--form 'mask_image_url="https://replicate.delivery/pbxt/M0gpLCYdCLbnhcz95Poy66q30XW9VSCN65DoDQ8IzdzlQonw/kill-bill-mask.png"'{
"task_id": "task_1234567890abcdef",
"tasks_ahead_count": 2,
"estimate_image_time": 120
}{
"error": "user_input must be less than 200 characters"
}POST https://api.genaifactory.ai/v1/assetsapp-id
string
Yes
Must be "flickbloom"
authorization
string
Yes
Bearer token for user authentication
asset_url
string
Yes
Specifies the asset url to create
description
object
No
Describle the asset
curl --location 'http://localhost:3300/v1/assets' \
--header 'app-id: flickbloom' \
--header 'authorization: Bearer YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"asset_url":"https://cdn.genaifactory.ai/assets/flickbloom/FkuKvdmVvJdMswE4iiuE7Y4mwKD2/2d6e2fdbdf9940c493e90efc5075e277_output_mixed.mp4",
"description":"abc"
}'
{
"created_at": "2025-04-10T02:27:45.502339+00:00",
"description": "abc",
"file_type": "mp4",
"id": 16,
"url": "https://cdn.genaifactory.ai/assets/flickbloom/FkuKvdmVvJdMswE4iiuE7Y4mwKD2/2d6e2fdbdf9940c493e90efc5075e277_output_mixed.mp4"
}DELETE https://api.genaifactory.ai/v1/assets/{asset_id}app-id
string
Yes
Must be "flickbloom"
authorization
string
Yes
Bearer token for user authentication
asset_id
int
Yes
ID of the asset
curl --location --request DELETE 'https://api.genaifactory.ai/v1/assets/1' \
--header 'app-id: flickbloom' \
--header 'authorization: Bearer YOUR_JWT_TOKEN'{
"message": "Asset with id 123 has been deleted"
}PATCH https://api.genaifactory.ai/v1/assets/{asset_id}app-id
string
Yes
Must be "flickbloom"
authorization
string
Yes
Bearer token for user authentication
asset_id
int
Yes
ID of the asset
{
"description": "Updated asset description"
}curl --location --request PATCH 'https://api.genaifactory.ai/v1/assets/1' \
--header 'app-id: flickbloom' \
--header 'authorization: Bearer YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"description":"a jpg"
}'{
"id": 123,
"url": "https://.../image1.png",
"description": "Updated asset description",
"file_type": "png"
}Session
API Endpoint
GET https://api.genaifactory.ai/v1/conversation_history/{session_id}formacloud-api-key
string
Yes
API key for authentication
Query Parameters
last_step_only
boolean
No
If true, returns only the last step
page
int
No
Page number (default: 0)
page_size
int
No
Number of steps per page (default: 10, max: 25)
Example Request
curl --location 'https://api.genaifactory.ai/v1/conversation_history/shuxuan-test-1?page=0&page_size=10' \
--header 'formacloud-api-key: abc123'Response
Returns a JSON object containing the conversation history.
session_id
string
Unique session identifier
goal
string
The goal of the conversation
steps
array
List of conversation steps
pagination
object
Pagination details
Example Response
{
"goal": "Ask the user what he/she wants, and help them create it.",
"pagination": {
"current_page": 0,
"total_pages": 1,
"total_records": 3
},
"session_id": "shuxuan-test-1",
"steps": [
{
"agent_response": {
"action": "AskUser",
"parameters": {
"question": "Hello! I'm here to help you create something amazing. What would you like to create today? I can help with:\n\n1. Creating images from text descriptions\n2. Converting images to short videos\n3. Processing and analyzing images\n4. Creating HTML visualizations\n\nPlease let me know what you have in mind, and I'll help plan and execute it step by step!"
},
"reasoning": "Since this is the start of our interaction and there's no specific request yet in the history, I should first understand what the user wants to create. As a master planner, I need to gather initial requirements before proposing any specific approach.",
"selected_tool": ""
},
"id": 0,
"step_result": "create a dog image",
"timestamp": "2025-02-21T04:13:24.128311+00:00"
},
{
"agent_response": {
"action": "AskUser",
"parameters": {
"question": "I'll help you create a wonderful dog picture! To make sure I generate exactly what you're looking for, could you please provide more details about:\n\n1. What breed of dog would you like? (e.g., Golden Retriever, Corgi, etc.)\n2. What should the dog be doing? (e.g., sitting, playing, sleeping)\n3. What kind of setting or background would you prefer? (e.g., park, home, beach)\n4. Any specific style you'd like? (e.g., realistic, cartoon, artistic)\n\nThis will help me create the perfect dog picture for you!"
},
"reasoning": "The user wants to create a dog picture. Since we have access to the 'generate_image_by_recraft' tool that can create images from text descriptions, I should first get more specific details about what kind of dog picture they want to create to ensure the best results. This aligns with being a perfectionist and ensuring we create exactly what they envision.",
"selected_tool": ""
},
"id": 1,
"step_result": "a playing dog",
"timestamp": "2025-02-21T04:14:17.644225+00:00"
},
{
"agent_response": {
"action": "CallTool",
"parameters": {
"prompt": "A joyful and energetic dog playing outdoors, captured mid-action with a wagging tail and happy expression. The dog is jumping playfully with a bouncy, enthusiastic pose. Bright, cheerful lighting with a natural background. The image should convey happiness and movement, with the dog showing clear signs of enjoyment like a wide doggy smile and alert, excited eyes. High quality, detailed, vibrant colors."
},
"reasoning": "The user wants to create a picture of a playful dog. Since we want to create the best possible image, I should use the generate_image_by_recraft tool with a detailed prompt that captures a playful, energetic scene. I'll focus on creating a prompt that emphasizes the dog's playful nature and dynamic movement to make the image engaging and lively.",
"selected_tool": "generate_image_by_recraft"
},
"id": 2,
"step_result": "https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/2/21/b9a62524b436468d9eaa106c986e84e9.png",
"timestamp": "2025-02-21T04:15:10.998182+00:00"
}
]
}API Endpoint
POST https://api.genaifactory.ai/v1/upload_imagesHeaders
app-id
string
Yes
Must be "flickbloom"
authorization
string
Yes
Bearer token for user authentication
Request Parameters
images
file[]
Yes
List of images (max 10 files, max 200MB per file)
The uploaded files must be in one of the allowed formats:
Images: PNG, JPG, JPEG, GIF, BMP, WEBP, SVG
Documents: PDF
Audio/Video: MP4, AVI, MP3, FLAC, WAV
The maximum file size per image is 200MB.
A maximum of 10 files can be uploaded at once.
Example Request
curl --location 'https://api.genaifactory.ai/v1/upload_images' \
--header 'app-id: flickbloom' \
--header 'authorization: Bearer YOUR_JWT_TOKEN' \
--form 'images=@"/path/to/image1.png"' \
--form 'images=@"/path/to/document.pdf"' \
--form 'images=@"/path/to/audio.mp3"' \
--form 'descriptions=["A sample image", "A PDF document", "Audio clip"]'
Response
Success Response (200 OK)
{
"image_urls": [
"https://storage.example.com/assets/user1/image1.png",
"https://storage.example.com/assets/user1/document.pdf",
"https://storage.example.com/assets/user1/audio.mp3"
]
}
Error Responses
1. No images provided (400 Bad Request)
{
"error": "No files found"
}2. Too many files (400 Bad Request)
{
"error": "Maximum 10 files are allowed"
}3. Invalid file type (400 Bad Request)
{
"error": "example.txt File type not allowed."
}4. File exceeds max size (400 Bad Request)
{
"error": "image.jpg exceeds maximum file size of 200MB. File size: 210MB"
}API Endpoint
POST https://api.genaifactory.ai/v1/start_conversationHeaders
formacloud-api-key
string
Yes
API key for authentication
Request Body
goal
string
Yes
The goal or topic of the conversation
session_id
string
No
An optional session ID (auto-generated if empty)
Example Request
curl --location 'https://api.genaifactory.ai/v1/start_conversation' \
--header 'formacloud-api-key: abc123' \
--header 'Content-Type: application/json' \
--data '{
"goal":"Ask the user what he/she wants, and help them create it.",
"session_id":"shuxuan-test-1"
}'Response
Returns a JSON object containing session details and the first conversation step.
session_id
string
Unique session identifier
current_step
object
The current step in the conversation
Example Response
{
"current_step": {
"agent_response": {
"action": "AskUser",
"parameters": {
"question": "Hello! I'm here to help you create something amazing. What would you like to create today? I can help with:\n\n1. Creating images from text descriptions\n2. Converting images to short videos\n3. Processing and analyzing images\n4. Creating HTML visualizations\n\nPlease let me know what you have in mind, and I'll help plan and execute it step by step!"
},
"reasoning": "Since this is the start of our interaction and there's no specific request yet in the history, I should first understand what the user wants to create. As a master planner, I need to gather initial requirements before proposing any specific approach.",
"selected_tool": ""
},
"id": 0,
"step_result": null,
"timestamp": "2025-02-21T04:13:24.128311+00:00"
},
"session_id": "shuxuan-test-1"
}This API retrieves the status and details of a specific task using its unique task_id.
GET https://api.genaifactory.ai/v1/task/{task_id}
Returns a JSON object containing the status, input, output, and details of the requested task.The response will vary based on the task status:
Success Response (Status Code 200): Indicates the task completed successfully. The response includes the final output and all relevant task details.
Running Response (Status Code 202): Indicates the task is still in progress. The response includes partial details and status updates.
Pending Response (Status Code 201): Indicates the task has been created but has not started execution yet. The response includes the task identifier and basic metadata.
Failure Response (Status Code 4XX): Indicates an error occurred during task execution or validation. The response includes an error message and details explaining the failure.
Input Data (input_data)
Output Data (output_data)
Example Response
This API retrieves or generates an SVG version of the output image for a specific task ID. The response includes the SVG URL of the requested image.
Returns a JSON object containing the SVG URL of the requested image.
Response Fields
Example Response
The image_metrics endpoint allows you to query the performance, costs, and other metrics related to the creation of images within a specified period. This information can help you evaluate the effectiveness and resource usage of the image creation process over time.
API Endpoint
To retrieve the metrics, send a GET request to the following URL:
GET https://api.genaifactory.ai/v1/image_metrics
Headers
Ensure that your request includes the following header:
Query Parameters
You can use the following query parameters to specify the time period for which you want to retrieve metrics:
Response Body
The response will include the following metrics related to image creation within the specified period:
Example Request
Example Response
Success Response (Status Code 200)
Failure Response (Status Code 4XX)
Endpoint
Headers
Query Parameters
Example Request
Response
Error Responses
401 Unauthorized – Missing or invalid token
400 Bad Request – Invalid query params (e.g., non-integer page)
formalcloud-api-key
string
Yes
API key for authentication
task_id
integer
Yes
The unique identifier of the task.
curl --location 'http://api.genaifactory.ai/v1/task/333' \
--header 'formacloud-api-key: to replace' \
--data ''created_at
string
The timestamp when the task was created.
finished_at
string
The timestamp when the task was completed.
input_data
array
An array containing the input data for the task.
language_code
string
The language code detected for the input data.
output_data
array
An array containing the output data of the task, if available.
task_id
integer
The unique identifier for the task.
task_status
string
The current status of the task (CREATED, RUNNING, SUCCESS, or FAILED).
task_type
string
The type of task created.
type
string
The type of the input (e.g., text).
text
object
Contains the input text content.
type
string
The type of the output (e.g., audio).
url
string
The URL to access the generated output.
length
float
The duration of the output in seconds.
{
"created_at": "Sat, 16 Nov 2024 05:24:47 GMT",
"finished_at": "Sat, 16 Nov 2024 05:26:03 GMT",
"input_data": [
{
"text": {
"content": "To resolve this issue, you can run the command as the root user in the Dockerfile. By default, the Docker build process executes commands as root, so this is often a configuration or permissions issue in the Docker environment. Below are several ways to address the issue"
},
"type": "text"
}
],
"language_code": "en",
"output_data": [
{
"length": 17.31918367346939,
"type": "audio",
"url": "https://cdn.genaifactory.ai/gen_ai_factory/temp/audio/2024/11/16/0bcc4bc2128142d3b483eddbc1f32a07.mp3"
}
],
"task_id": 333,
"task_status": "SUCCESS",
"task_type": "TTS"
}GET https://api.genaifactory.ai/v1/export_svg/<task_id>formacloud-api-key
string
Yes
API key for authentication.
seq
integer
No
Sequence number of the output image (default is 0).
task_id
string
Yes
The unique ID of the task to export the SVG for.
curl --location 'https://api.genaifactory.ai/v1/export_svg/12345' \
--header 'formacloud-api-key: abc123' \
--header 'Content-Type: application/json' \
--request GET \
--data-urlencode "seq=0"svg_url
string
URL of the exported SVG image.
{
"svg_url": "https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2024/12/16/7439a85e8339405b9ae680dc454f75f2.svg"
}404
TaskNotFoundError
The specified task ID does not exist.
400
InvalidInputError
The input is invalid (e.g., seq out of range).
400
InvalidInputError
Task is not a valid POSTER type.
Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
Name
Type
Required
Description
start
string
No
The start date of the metrics collection period in UTC (e.g., 2023-01-01T00:00:00Z).
end
string
No
The end date of the metrics collection period in UTC (e.g., 2023-01-31T23:59:59Z).
Name
Type
Required
Description
total_images
int
Yes
The total number of images created within the specified period.
total_cost
number
Yes
The total cost associated with creating the images within the specified period.
average_time
number
Yes
The average time taken to create each image within the specified period, in seconds.
curl -G 'https://api.genaifactory.ai/v1/image_metrics' \
-H 'formacloud-api-key: abc123' \
--data-urlencode "start=2023-01-01T04:16:39Z&end=2023-01-31T12:25:47Z"{
"total_images": 45,
"total_cost": 12.50,
"average_time": 3.5
}{
"error": "Invalid date range",
}GET https://api.genaifactory.ai/v1/assetsapp-id
string
Yes
Must be "flickbloom"
authorization
string
Yes
Bearer token for user authentication
start
ISO 8601
No
Start datetime filter (e.g., 2024-01-01T00:00:00Z)
end
ISO 8601
No
End datetime filter
page
integer
No
Page number (default: 0)
page_size
integer
No
Number of items per page (default: 25)
type
string
No
The asset type: audio, video, image, document
curl --location 'https://api.genaifactory.ai/v1/assets?type=image' \
--header 'app-id: flickbloom' \
--header 'authorization: Bearer YOUR_JWT_TOKEN'
{
"assets": [
{
"id": 123,
"url": "https://.../image1.png",
"description": "Sample file",
"file_type": "png"
}
],
"pagination": {
"current_page": 0,
"total_pages": 5,
"total_records": 124
}
}This API allows users to fetch a paginated list of conversation histories within a specified time range.
Endpoint
GET https://api.genaifactory.ai/v1/all_sessionsHeaders
formacloud-api-key
string
Yes
API key for authentication
Query Parameters
start
string (ISO 8601)
No
Start timestamp (UTC) in ISO 8601 format (e.g., 2024-02-20T00:00:00Z). If not provided, no lower limit is applied.
end
string (ISO 8601)
No
End timestamp (UTC) in ISO 8601 format (e.g., 2024-02-21T00:00:00Z). If not provided, no upper limit is applied.
page
int
No
Page number (default: 0).
page_size
int
No
Number of records per page (default: 10).
Example Request
Fetch Conversation History (Default Pagination)
curl --location 'https://api.genaifactory.ai/v1/all_sessions?page=0&page_size=10' \
--header 'formacloud-api-key: abc123'Fetch History Within a Time Range
curl --location 'https://api.genaifactory.ai/v1/all_sessions?start=2024-02-20T00:00:00Z&end=2024-02-21T00:00:00Z&page=1&page_size=5' \
--header 'formacloud-api-key: abc123'Response
Returns a JSON object containing conversation history and pagination details.
Response Fields
history
array
List of conversation history records
goal
string
The goal of the conversation
session_id
string
Unique session identifier
created_at
string (ISO 8601)
The timestamp when the session was created
pagination
object
Pagination metadata
current_page
int
The current page number
total_pages
int
The total number of pages
total_records
int
The total number of history records
Example Response
{
"history": [
{
"created_at": "2025-02-25T11:37:30.872055+00:00",
"goal": "Ask the user what he/she wants, and help them create it.",
"session_id": "shuxuan-test-4"
},
{
"created_at": "2025-02-25T11:24:30.659717+00:00",
"goal": "Ask the user what he/she wants, and help them create it.",
"session_id": "shuxuan-test-3"
},
{
"created_at": "2025-02-24T22:12:07.973776+00:00",
"goal": "Create a promo video for me",
"session_id": "79caaf6d-6607-44ca-9829-f7d8cba6e44c"
},
{
"created_at": "2025-02-24T22:01:21.519001+00:00",
"goal": "Create an image for me",
"session_id": "shan-1"
}
],
"pagination": {
"current_page": 0,
"total_pages": 1,
"total_records": 4
}
}This API is used to create a task for various purposes, such as generating audio content based on the specified parameters and input data.
POST https://api.genaifactory.ai/v1/create_task
Parameters (params)
Input Data (input_data)
Text Object
Returns a JSON object containing the task details.
Example Response
The recharge_history endpoint allows you to query the history of recharge transactions for an organization. It includes details such as the recharge amount, bonus amount, payment method, transaction ID, and creation time. This endpoint supports pagination to efficiently navigate through historical records.
To retrieve recharge history, send a GET request to the following URL:
GET https://api.genaifactory.ai/v1/recharge_history
Ensure that your request includes the following header:
You can use the following query parameters to specify the time period, pagination, and other details for retrieving the recharge history:
The response will include a list of recharge records and pagination details. Each recharge record contains the following information:
Success Response (Status Code 200)
Failure Response (Status Code 4XX)
API Endpoint
Headers
Available Action Types
Request Body
Example Request
When ActionType = ASK_USER (user_input is required)
When ActionType is NOT ASK_USER (send an empty {})
Get the latest step result without executing a new step
Response
Returns a JSON object containing the updated conversation step.
Response Handling
If the response contains:ActionType = CALL_TOOL, you must call this API again to retrieve the step result.
Example Response 1
Example Response 2
Next Step: If "action": "CALL_TOOL" and "step_result": null, make another API request to get the step result.
formalcloud-api-key
string
Yes
API key for authentication
Content-Type
string
Yes
Must be set to application/json
task_type
string
Yes
Specifies the type of task to create:
TTS
params
object
Yes
Parameters specifying task details.
input_data
array of objects
Yes
Input data for the task.
reporter_voice
string
Yes
The reporter's voice model:
AMERICAN_MALE_1
AMERICAN_MALE_2
AMERICAN_MALE_3
AMERICAN_FEMALE_1
AMERICAN_FEMALE_2
AMERICAN_FEMALE_3
BRITISH_MALE_1
BRITISH_MALE_2
BRITISH_MALE_3
BRITISH_FEMALE_1
BRITISH_FEMALE_2
BRITISH_FEMALE_3
AUSTRALIAN_MALE_1
AUSTRALIAN_MALE_2
AUSTRALIAN_MALE_3
AUSTRALIAN_FEMALE_1
AUSTRALIAN_FEMALE_2
AUSTRALIAN_FEMALE_3
CANADIAN_MALE_1
CANADIAN_MALE_2
CANADIAN_MALE_3
CANADIAN_FEMALE_1
CANADIAN_FEMALE_2
CANADIAN_FEMALE_3
type
string
Yes
The type of input (e.g., text).
text
object
Yes
Contains the content to be processed.
content
string
Yes
The text content to process for the task.
curl --location 'http://api.genaifactory.ai/v1/create_task' \
--header 'formacloud-api-key: to replace' \
--header 'Content-Type: application/json' \
--data '{
"task_type": "TTS",
"params": {
"reporter_voice": "US_MALE_01"
},
"input_data": [
{
"type": "text",
"text": {
"content": "To resolve this issue, you can run the command as the root user in the Dockerfile. By default, the Docker build process executes commands as root, so this is often a configuration or permissions issue in the Docker environment. Below are several ways to address the issue"
}
}
]
}'created_at
string
The timestamp when the task was created.
task_id
integer
The unique identifier for the task.
task_status
string
The current status of the task.
task_type
string
The type of task created.
{
"created_at": "Sat, 16 Nov 2024 05:24:47 GMT",
"task_id": 333,
"task_status": "CREATED",
"task_type": "TTS"
}Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
Name
Type
Required
Description
start
string
No
The start date of the history retrieval period in UTC (e.g., 2023-01-01T00:00:00Z).
end
string
No
The end date of the history retrieval period in UTC (e.g., 2023-01-31T23:59:59Z).
page_size
int
No
The maximum number of records to retrieve per page (default: 10).
page
int
No
The page number to retrieve (default: 0).
Name
Type
Required
Description
recharge_id
int
Yes
The unique identifier of the recharge record.
recharge_amount
decimal
Yes
The amount of money recharged.
bonus_amount
decimal
No
The bonus amount received during the recharge.
payment_method
string
No
The payment method used for the recharge (e.g., Credit Card).
transaction_id
string
Yes
The unique transaction ID for the recharge.
note
string
No
Additional notes about the recharge.
recharge_time
string
Yes
The time when the recharge occurred, in UTC.
curl -G 'https://api.genaifactory.ai/v1/recharge_history' \
-H 'formacloud-api-key: abc123' \
--data-urlencode "start=2023-01-01T00:00:00Z&end=2023-01-31T23:59:59Z&page_size=10&page=1"{
"history": [
{
"recharge_id": 1,
"recharge_amount": 100.00,
"bonus_amount": 10.00,
"payment_method": "Credit Card",
"transaction_id": "TXN123456789",
"note": "Spring Promo",
"recharge_time": "2023-01-10T14:35:29Z"
},
{
"recharge_id": 2,
"recharge_amount": 200.00,
"bonus_amount": 0.00,
"payment_method": "PayPal",
"transaction_id": "TXN987654321",
"note": "",
"recharge_time": "2023-01-15T09:22:10Z"
}
],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_records": 50
}
}{
"error": "Invalid date range"
}POST https://api.genaifactory.ai/v1/conversations/{session_id}formacloud-api-key
string
Yes
API key for authentication
CALL_TOOL
"CallTool"
The system invokes an external tool to process the request. If this action is returned, the API must be called again to retrieve the tool's response.
ASK_USER
"AskUser"
The system requires user input to proceed. In this case, the user_input field must be provided in the next API call.
FINISH
"Finish"
The conversation session has reached its final state.
PLAN
"Plan"
The system is generating a structured plan for further execution.
CREATE_TOOL
"CreateTool"
The system dynamically creates a new tool or function based on the conversation's requirements.
user_input
string
Yes (if Last StepActionType = ASK_USER)
The user's response in the conversation. Required when the previous action type is ASK_USER. Otherwise, send an empty {}.
query_step_result
bool
No
If true, the API only returns the latest step result without executing a new step. (default: false)
curl --location 'https://api.genaifactory.ai/v1/conversations/shuxuan-test-1' \
--header 'formacloud-api-key: abc123' \
--header 'Content-Type: application/json' \
--data '{
"user_input": "create a dog image"
}'curl --location 'https://api.genaifactory.ai/v1/conversations/shuxuan-test-1' \
--header 'formacloud-api-key: abc123' \
--header 'Content-Type: application/json' \
--data '{}'curl --location 'https://api.genaifactory.ai/v1/conversations/shuxuan-test-1' \
--header 'formacloud-api-key: abc123' \
--header 'Content-Type: application/json' \
--data '{"query_step_result": true}'session_id
string
Unique session identifier
current_step
object
The latest step in the conversation
{
"current_step": {
"agent_response": {
"action": "AskUser",
"parameters": {
"question": "I'll help you create a dog image! To get the best result, could you please provide more details about:\n\n1. What breed of dog would you like? (e.g., Golden Retriever, Husky, etc.)\n2. What should the dog be doing? (e.g., sitting, running, playing)\n3. Any specific setting or background you'd like? (e.g., park, beach, home)\n4. Any particular style you prefer? (e.g., realistic, cartoon, artistic)\n\nThe more details you provide, the better the image will match your vision!"
},
"reasoning": "The user wants to create a dog image. We can use the text-to-image generation tool (generate_image_by_recraft) for this. However, before generating the image, I should ask for more specific details about the type of dog image they want to ensure we get the best possible result.",
"selected_tool": ""
},
"id": 1,
"step_result": null,
"timestamp": "2025-02-21T04:48:59.812834+00:00"
},
"session_id": "shuxuan-test-1"
}{
"current_step": {
"agent_response": {
"action": "CallTool",
"parameters": {
"prompt": "A photorealistic dog running at full speed in an open field with grass. The dog's muscles are tense, fur flowing in the wind, captured in mid-stride with all four paws off the ground. Natural lighting, high detail, crisp focus on the dog's determined expression."
},
"reasoning": "The user has requested a running and realistic dog image. Now I need to generate this image using the 'generate_image_by_recraft' tool, which allows for text-to-image generation. I'll craft a detailed prompt to create the realistic running dog image the user wants.",
"selected_tool": "generate_image_by_recraft"
},
"id": 2,
"step_result": null,
"timestamp": "2025-02-25T11:38:51.634443+00:00"
},
"session_id": "shuxuan-test-1"
}The image_history endpoint allows you to query the history of image creation, including the input parameters, creation time, and response results (both successful and failed) within a specified period. This endpoint supports pagination to navigate through large sets of historical data.
API Endpoint
To retrieve the image creation history, send a GET request to the following URL:
GET https://api.genaifactory.ai/v1/image_history
Headers
Ensure that your request includes the following header:
Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
Query Parameters
You can use the following query parameters to specify the time period, pagination, and other details for retrieving the image history:
Name
Type
Required
Description
start
string
No
The start date of the history retrieval period in UTC (e.g., 2023-01-01T00:00:00Z).
end
string
No
The end date of the history retrieval period in UTC (e.g., 2023-01-31T23:59:59Z).
page_size
int
No
The maximum number of records to retrieve per page (default: 10).
page
int
No
The page number to retrieve (default: 1).
task_types
string
No
A comma-separated list of task types to filter results (e.g., POSTER,IMG_WITHOUT_TEXT). Supported values include task types such as POSTER, IMG_WITHOUT_TEXT, and REDRAW_IMAGE. If not provided, the default is POSTER,IMG_WITHOUT_TEXT.
Response Body
The response will include a list of image creation records, each containing the following details:
Name
Type
Required
Description
create_time
string
Yes
The time when the image was created, in UTC.
input_parameters
object
Yes
The input parameters used for creating the image, including struct_content, logo_url, main_image_url, and image_count.
response_result
object
Yes
The response result of the image creation, including the success or failure response.
Example Request two
curl -G 'https://api.genaifactory.ai/v1/image_history' \
-H 'formacloud-api-key: abc123' \
--data-urlencode "start=2023-01-01T00:00:00Z&end=2023-01-31T23:59:59Z&page_size=10&page=1"
curl --location 'https://api.genaifactory.ai/v1/image_history?page_size=2&page=1&task_types=REDRAW_IMAGE' \
--header 'formacloud-api-key: abc123' \
--data ''Example Response two
Success Response (Status Code 200)
{
"history": [
{
"creation_time": "2025-01-07T21:06:26.632791+00:00",
"input_parameters": {
"image": "https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/1/7/a32840a4846e48658b3d36378c6992a3.jpg",
"mask": "https://replicate.delivery/pbxt/M0gpLCYdCLbnhcz95Poy66q30XW9VSCN65DoDQ8IzdzlQonw/kill-bill-mask.png",
"prompt": "formacloud"
},
"response_result": {
"created_at": "2025-01-07 21:06:26.632791 +00:00",
"finished_at": "2025-01-07 21:06:41.584666 +00:00",
"images": [
"https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/1/7/57f04b22c19549bb95c548dc388bfb68.png"
],
"images_model_names": [],
"poster_imgs": [
"https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/1/7/57f04b22c19549bb95c548dc388bfb68.png"
],
"poster_svg_imgs": [
null
],
"started_at": "2025-01-07 21:06:26.828427 +00:00",
"svg_images": [
null
]
},
"task_id": 6928
},
{
"creation_time": "2025-01-07T20:45:50.173454+00:00",
"input_parameters": {
"image": "https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/1/7/c26c9814f7e4428c971b8c3a63bd8890.jpg",
"mask": "https://replicate.delivery/pbxt/M0gpLCYdCLbnhcz95Poy66q30XW9VSCN65DoDQ8IzdzlQonw/kill-bill-mask.png",
"prompt": "movie poster says \\\"moonveil\\\"\""
},
"response_result": {
"created_at": "2025-01-07 20:45:50.173454 +00:00",
"error": "Error generating image: Cannot connect to host api.bfl.ml:443 ssl:default [Connect call failed ('74.241.144.241', 443)]",
"finished_at": "2025-01-07 20:45:57.575906 +00:00",
"images": [],
"images_model_names": [],
"poster_imgs": [],
"poster_svg_imgs": [],
"started_at": "2025-01-07 20:45:50.328150 +00:00",
"status": "The task encountered an error and did not complete successfully.",
"svg_images": []
},
"task_id": 6927
}
],
"pagination": {
"current_page": 1,
"total_pages": 9,
"total_records": 18
}
}Failure Response (Status Code 4XX)
{
"error": "Invalid date range",
}The get_image_result endpoint allows you to retrieve the final result of a image generation task that was processed asynchronously. By providing the task ID returned from the create_images endpoint when async was set to true, you can check the status of the task and obtain the generated images once the task is complete.
API Endpoint
To retrieve the image generation result, send a GET request to the following URL:
GET https://api.genaifactory.ai/v1/get_image_result/{task_id}
Headers
Ensure that your request includes the following header:
Path Parameters
Response Body
Pending Response (Status Code 201)
If the task is still in queue, the response will indicate that the task does not start:
Running Response (Status Code 202)
If the task is still in progress, the response will indicate that the task is not yet complete:
Success Response (Status Code 200)
If the task has completed successfully, the response will include the generated images:
Failure Response (Status Code 4XX)
If there is an issue with the request, such as an invalid task ID, the response will include an error message:
Example Request
Example Pending Response
Example Running Response
Example Successful Response
Example Failure Response
Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
Name
Type
Required
Description
task_id
string
Yes
The ID of the task you received when you initially made the asynchronous request.
Name
Type
Required
Description
status
string
Yes
A message indicating that the task is still processing, this field will be CREATED.
created_at
string
Yes
The timestamp indicating when the task was created.
tasks_ahead_count
int
Yes
The number of tasks ahead of it will be returned from the time a task is created until it is executed
Name
Type
Required
Description
status
string
Yes
A message indicating that the task is still processing, this field will be RUNNING.
created_at
string
Yes
The timestamp indicating when the task was created.
started_at
string
Yes
The timestamp indicating when the task began processing.
Name
Type
Required
Description
status
string
Yes
The status of the task. For successful completion, this field will be SUCCESS.
created_at
string
Yes
The timestamp indicating when the task was created.
started_at
string
Yes
The timestamp indicating when the task began processing.
finished_at
string
Yes
The timestamp indicating when the task finished processing.
images
array of strings
No
A list of URLs pointing to the generated images in PNG format. Each URL corresponds to a generated image. The images are retained for a maximum duration of one month.
images_model_names
array of arrays
No
A list of arrays indicating the model names used to generate each image. Each inner array corresponds to one image.
svg_images
array of strings
No
A list of URLs pointing to the generated images in SVG format. Each URL corresponds to a generated image. The images are retained for a maximum duration of one month.
total_cost
string
Yes
The total cost of the task in currency units.
input_parameters
object
Yes
An object containing the parameters used to generate the task, such as image dimensions, style, content details, etc. Refer to the Input Parameters section below for details.
Name
Type
Required
Description
error
string
Yes
A descriptive error message indicating what went wrong with the request, this field will be
PARTIALLY_SUCCESSFUL or FAILED.
images
array of strings
No
A list of URLs pointing to the generated images in PNG format. Each URL corresponds to a generated image.
svg_images
array of strings
No
A list of URLs pointing to the generated images in SVG format. Each URL corresponds to a generated image.
curl --location 'https://api.genaifactory.ai/v1/get_image_result/task_1234567890abcdef' \
--header 'formacloud-api-key: [put the key here]' \
--header 'Content-Type: application/json'{
"status": "CREATED",
"tasks_ahead_count": 0,
"created_at": "2024-12-30 05:03:51.022874 +00:00"
}{
"status": "RUNNING",
"created_at": "2024-12-30 05:03:51.022874 +00:00",
"started_at": "2024-12-31 01:34:00.414493 +00:00"
}{
"status": "SUCCESS",
"created_at": "2024-12-30 05:03:51.022874 +00:00",
"started_at": "2024-12-30 05:03:51.572481 +00:00",
"finished_at": "2024-12-30 05:06:35.493555 +00:00",
"images": [
"https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2024/12/30/32deb38c95cb472a99de75aba5bb9e8e.png",
],
"svg_images": [
null,
],
"images_model_names": [
["M6"],
],
"total_cost": "1.6000",
"input_parameters": {
"create_background": true,
...
}
}{
"error": "'builtin_function_or_method' object has no attribute 'sleep'",
"images": [
"https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2024/10/9/97b1901d1e5c4bb499a67d82cd16b5cd.png"
],
"status": "PARTIALLY_SUCCESSFUL",
"svg_images": [
null,
]
}Example Request one
curl -G 'https://api.genaifactory.ai/v1/image_history' \
-H 'formacloud-api-key: abc123' \
--data-urlencode "start=2023-01-01T00:00:00Z&end=2023-01-31T23:59:59Z&page_size=10&page=1"Example Response one
Success Response (Status Code 200)
```json
{
"history": [
{
"creation_time": "2025-01-15T23:43:14.616443+00:00",
"input_parameters": {
"create_image_without_text": true,
"freeform_content": "Subject: A sleeping tabby cat\r\nDetails: Striped brown, black and white fur pattern, curled up position, peaceful sleeping expression, visible whiskers, soft fur texture\r\nEnvironment: Grey plush blanket, white duck-shaped night light in background, warm sunlit indoor setting\r\nStyle: Natural photography with soft focus\r\nComposition: Close-up horizontal frame, cat centered, decorative duck lamp providing background interest\r\nLighting: Natural sunlight creating gentle highlights on fur, warm ambient glow\r\nQuality: High resolution with sharp detail capture, professional depth of field",
"image_count": "1",
"industry": "Finance/Insurance",
"poster_count": 1,
"resolution": "RESOLUTION_1248_702",
"style": "WATERCOLOR"
},
"response_result": {
"created_at": "2025-01-15 23:43:14.616443 +00:00",
"finished_at": "2025-01-15 23:43:29.732993 +00:00",
"images": [
"https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/1/15/39e9b78a50b04f239406fddb46371c3b.png"
],
"images_model_names": [
[
"M6"
]
],
"poster_imgs": [
"https://cdn.genaifactory.ai/gen_ai_factory/temp/image/2025/1/15/39e9b78a50b04f239406fddb46371c3b.png"
],
"poster_svg_imgs": [
null
],
"started_at": "2025-01-15 23:43:14.763913 +00:00",
"svg_images": [
null
]
},
"task_id": 7384
}
],
"pagination": {
"current_page": 100,
"total_pages": 3911,
"total_records": 3911
}
}
```The image_costs endpoint allows you to retrieve a breakdown of the costs associated with image generation tasks, including cloud compute costs, LLM token costs, image generation costs, and more. This endpoint supports pagination for navigating large sets of historical task data.
To retrieve image generation costs, send a GET request to the following URL:
GET https://api.genaifactory.ai/v1/image_costs
Ensure that your request includes the following header:
Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
You can use the following query parameters to specify pagination details for retrieving image cost history:
Name
Type
Required
Description
start
string
No
The start date of the history retrieval period in UTC (e.g., 2023-01-01T00:00:00Z).
end
string
No
The end date of the history retrieval period in UTC (e.g., 2023-01-31T23:59:59Z).
page_size
int
No
The maximum number of records to retrieve per page (default: 10).
page
int
No
The page number to retrieve (default: 1).
The response will include a list of image generation cost records, each containing the following details:
task_id
int
Yes
Unique identifier of the image generation task.
poster_count
int
No
The number of posters created in the task.
task_status
string
Yes
Status of the task (e.g., SUCCESS, FAILED).
creation_time
string
Yes
The time when the image generation task was created (in UTC).
end_time
string
No
The time when the image generation task was completed (in UTC), if applicable.
total_cost
float
Yes
The total cost of the task.
error_msg
string
No
Error message associated with the task, if it failed.
Example Request
curl -G 'https://api.genaifactory.ai/v1/image_costs' \
-H 'formacloud-api-key: abc123' \
--data-urlencode "start=2023-01-01T00:00:00Z&end=2023-01-31T23:59:59Z&page_size=10&page=1"Example Response
Success Response (Status Code 200):
{
"image_costs": [
{
"creation_time": "2024-10-28T19:24:30.327236+00:00",
"end_time": "2024-10-28T19:27:25.818746+00:00",
"poster_count": 3,
"task_id": 1900,
"task_status": "SUCCESS",
"total_cost": "1.4100"
},
{
"ai_image_generation_cost": "1.2060",
"creation_time": "2024-10-28T19:24:26.066261+00:00",
"end_time": "2024-10-28T19:27:14.994364+00:00",
"poster_count": 4,
"task_id": 1899,
"task_status": "SUCCESS",
"total_cost": "1.8800",
}
],
"pagination": {
"current_page": 1,
"total_pages": 902,
"total_records": 1803
}
}Failure Response (Status Code 4XX):
{
"error": "Invalid page number."
}The create_images endpoint allows you to generate custom-designed images by providing key content elements such as structured texts, free-from texts, logos, and images. This API simplifies the creation of visually appealing images for various use cases, such as marketing materials, announcements, and informational displays.
API Endpoint
To create an image, send a POST request to the following URL:
POST https://api.genaifactory.ai/v1/create_images
Headers
Ensure that your request includes the following header:
Name
Type
Required
Description
formacloud-api-key
string
Yes
API key required for authenticating your request.
Request Body
The request body should be sent as form-data and include the following fields.
Name
Type
Required
Description
structured_content
object (JSON in string format)
No
Structured content for the image, including detailed sections like primary information, secondary information, features, button text, and warnings or hints. This should be passed as a string in JSON format.
freeform_content
string
No
Unstructured text content for the image. If provided, this will be used along with structured_content. Both will be utilized; however, in case of any conflict, Primary Text will take precedence. If create_image_without_text is set to True, the field is mandatory.
logo_image
file
No
The logo image file to be included on the image. This allows you to upload a file for branding the image with a company logo. While there are no specific size or dimension validations during upload, the logo image size will be restricted during usage. In the final rendered image, the logo image's size will not exceed 1/9 of the total image dimensions.
logo_url
string
No
The URL of a logo image to include in the image. Only either logo_image or logo_url should be provided.
main_images
file[]
No
One or more main image files that you want to include in the image. Multiple files can be uploaded, with a maximum limit of three main images. If both main_images and main_image_urls are provided, the uploaded main_images will take priority.
There are no specific size or dimension validations during upload. However, when used in the final rendered image, the size of each main_image will be adjusted to fit within the final output.
main_image_urls
array of strings (JSON in string format)
No
A list of URLs for the main images that should be included in the image. This can be used when image files are not uploaded directly. A maximum of three main images can be included.
There are no specific size or dimension validations for the images provided via URLs. However, when used in the final rendered image, the size of each main image will be adjusted to fit within the final output.
background_image
file
No
A background image file to be used for the image. Only either background_image or background_image_url should be provided.
background_image_url
string
No
The URL of a background image to include in the image. This will be used if no background_image is uploaded.
style
string
No
The style of the image. The options include: "REALISTIC",""CARTOON,"ANIME","OIL_PAINTING","WATERCOLOR","PENCIL_SKETCH","INK_WASH","CHARCOAL","UKIYO_E","POP_ART","PIXEL_ART","VINTAGE","THREE_D_RENDER","CLAY","SURREALISM","SCI_FI","RANDOM".
image_count
int
No
The number of images to generate. Default is 1.
export_svg
boolean
No
If set to true, the image will be exported as an SVG format. Default is false.
resolution
string
No
Specifies the resolution of the image. Cannot be used together with width and height. Acceptable values are: RESOLUTION_512_1536, RESOLUTION_576_1408, RESOLUTION_576_1472, RESOLUTION_576_1536, RESOLUTION_640_1024, RESOLUTION_640_1344, RESOLUTION_640_1408, RESOLUTION_640_1472, RESOLUTION_640_1536, RESOLUTION_704_1152, RESOLUTION_704_1216, RESOLUTION_704_1280, RESOLUTION_704_1344, RESOLUTION_704_1408, RESOLUTION_704_1472, RESOLUTION_720_1280, RESOLUTION_736_1312, RESOLUTION_768_1024, RESOLUTION_768_1088, RESOLUTION_768_1152, RESOLUTION_768_1216, RESOLUTION_768_1232, RESOLUTION_768_1280, RESOLUTION_768_1344, RESOLUTION_832_960, RESOLUTION_832_1024, RESOLUTION_832_1088, RESOLUTION_832_1152, RESOLUTION_832_1216, RESOLUTION_832_1248, RESOLUTION_864_1152, RESOLUTION_896_960, RESOLUTION_896_1024, RESOLUTION_896_1088, RESOLUTION_896_1120, RESOLUTION_896_1152, RESOLUTION_960_832, RESOLUTION_960_896, RESOLUTION_960_1024, RESOLUTION_960_1088, RESOLUTION_1024_640, RESOLUTION_1024_768, RESOLUTION_1024_832, RESOLUTION_1024_896, RESOLUTION_1024_960, RESOLUTION_1024_1024, RESOLUTION_1088_768, RESOLUTION_1088_832, RESOLUTION_1088_896, RESOLUTION_1088_960, RESOLUTION_1120_896, RESOLUTION_1152_704, RESOLUTION_1152_768, RESOLUTION_1152_832, RESOLUTION_1152_864, RESOLUTION_1152_896, RESOLUTION_1216_704, RESOLUTION_1216_768, RESOLUTION_1216_832, RESOLUTION_1232_768, RESOLUTION_1248_832, RESOLUTION_1280_704, RESOLUTION_1280_720, RESOLUTION_1280_768, RESOLUTION_1280_800, RESOLUTION_1312_736, RESOLUTION_1344_640, RESOLUTION_1344_704, RESOLUTION_1344_768, RESOLUTION_1408_576, RESOLUTION_1408_640, RESOLUTION_1408_704, RESOLUTION_1472_576, RESOLUTION_1472_640, RESOLUTION_1472_704, RESOLUTION_1536_512, RESOLUTION_1536_576, RESOLUTION_1536_640, and RESOLUTION_1248_702. If not provided, defaults to RESOLUTION_1248_702.
width
int
No
Specifies the width of the image in pixels. Must be between 192 and 2000 if provided. Cannot be used together with resolution.
height
int
No
Specifies the height of the image in pixels. Must be between 192 and 2000 if provided. Cannot be used together with resolution.
create_background
boolean
No
A flag indicating whether to generate a background image. Must be a boolean value (true or false). If set to true, background_image or background_image_url must not be provided, as this will cause a conflict.
create_main_image
boolean
No
A flag indicating whether to generate a main image. Must be a boolean value (true or false). This parameter controls the inclusion of a main image in the design process.
create_image_without_text
boolean
No
When set to true, this parameter instructs the system to generate an image without any text. In this mode, freeform_content must still be provided, even though it won't appear on the image. structured_content and any other text-related parameters are optional and will be ignored if provided. However, other non-text-related parameters (like style, and resolution) will still be applied to influence the visual style and layout of the image.
Structured Content Object
There are no strict character limits for any of the fields listed below. However, it is recommended to keep the total character count within 300 characters for optimal clarity and readability.
Name
Type
Required
Description
primary_text
string
Yes
The main headline or key information for the image.
secondary_text
string
No
Additional details or supporting information related to the primary info.
features
array of strings
No
A list of features or key points to be highlighted on the image. There is no strict limit on the number of features; however, it is recommended to include three or fewer for optimal clarity and impact.
action_button
string
No
The text for the call-to-action button on the image.
corner_hints
array of strings
No
A list of small hints or warning messages to be displayed on the corners of the image.There is no strict limit on the number of corner_hints; however, it is recommended to include two or fewer for optimal clarity and impact.
Response Body
Asynchronous Response (Status Code 202)
Name
Type
Required
Description
task_id
string
Yes
The ID of the task that was created. You can use this ID to retrieve the image generation results at a later time.
tasks_ahead_count
int
Yes
The number of tasks ahead of it will be returned from the time a task is created until it is executed
estimate_image_time
int
Yes
The estimated time in seconds for the task to be executed based on recent task performance data.
Failure Response (Status Code 4XX or 5XX)
Name
Type
Required
Description
error
string
Yes
A descriptive error message indicating what went wrong with the request.
Example Structured_content Request
curl --location 'https://api.genaifactory.ai/v1/create_images' \
--header 'formacloud-api-key: id9dqCjvEPNopJLhpu4VvoDAcBtPbTv3wkE2R5va4d0' \
--form 'poster_count="1"' \
--form 'create_background="true"' \
--form 'structured_content="{
\"features\": [
\"Make brand-perfect ads instantly\",
\"Test different ad versions while keeping your brand look\",
\"Reach global markets with accurate translations\"
],
\"corner_hints\": [\"\"],
\"primary_text\": \"Marketing and Advertising\",
\"action_button\": \"\",
\"secondary_text\": \"Empowered by Moonveil\"
}"' \
--form 'style="random"' \
--form 'create_main_image="true"' \
--form 'resolution="RESOLUTION_896_1120"'Example Freeform_content Request
curl --location 'https://api.genaifactory.ai/v1/create_images' \
--header 'formacloud-api-key: [put the key here]' \
--form 'freeform_content="A watercolor Christmas poster design featuring a robin perched on a branch with holly leaves and berries. The robin is singing. Below the bird, the text "Season\'s Greetings" is written in a cursive script. The background is a warm, golden hue. The overall design has a hand-painted feel."' \
--form 'logo_image=@"/Users/shuxuan/Pictures/hkdailynews.png"' \
--form 'main_images=@"/Users/shuxuan/Pictures/app.png"' \
--form 'image_count="1"'Example Create background image Request
curl --location 'https://api.genaifactory.ai/v1/create_images' \
--header 'formacloud-api-key: [put the key here]' \
--form 'freeform_content="A watercolor Christmas poster design featuring a robin perched on a branch with holly leaves and berries. The robin is singing. Below the bird, the text "Season\'s Greetings" is written in a cursive script. The background is a warm, golden hue. The overall design has a hand-painted feel."' \
--form 'logo_image=@"/Users/shuxuan/Pictures/hkdailynews.png"' \
--form 'main_images=@"/Users/shuxuan/Pictures/app.png"' \
--form 'image_count="1"'Example Asynchronous Response
{
"task_id": "task_1234567890abcdef",
"tasks_ahead_count": 3
}Example Failure Response
{
"error": "Invalid input data"
}