Harness the capabilities of AdLLM™, our proprietary AI model trained on over a billion high-converting ad texts, to create compelling and impactful ad copy effortlessly.
Overview
The Ad Text Generation API is a core feature designed to generate conversion-focused ad texts with the power of AdLLM Spark — the first AdLLM built specifically for crafting high-performing ad texts. This API empowers users with full control over the content and format of their ads, ensuring flexibility and customization.
What sets Ad Text Generation apart is its integration of proven copywriting frameworks, such as:
Before-After-Bridge: Highlighting the transformation enabled by the product/service.
AIDA (Attention, Interest, Desire, Action): Guiding users from initial attention to final conversion.
These methodologies are extensively tested and continuously optimized to maximize conversions, ensuring the generated ad texts deliver top performance.
Seamless Multi-Format Support
Ad Text Generation is not limited to a single ad type. It supports various ad formats, offering tailored packages for platforms like:
Meta Dynamic Ad Creatives
Google Performance Max Ads
With this feature, marketers and developers can generate all necessary ad texts for these formats within a single project, eliminating the need for time-consuming manual copywriting.
Key Benefits
✅ Conversion-optimized ad texts powered by AdLLM Spark.
✅ Full creative control over text content and format.
✅ Proven frameworks designed for performance.
✅ Multi-platform ad format support in a unified workflow.
✅ Saves significant time and effort in the ad creation process.
With Ad Text Generation API, you can skip the hassle of writing copy from scratch and instantly get ready-to-use, optimized ad texts tailored to your campaign needs.
Authorization
All endpoints requires the following headers for authentication and identification:
This endpoint generates advertising text (ad copy) based on provided product details, target audience, and customization options. It is designed to create compelling ad texts tailored to specific marketing needs, supporting various text types, tones, languages, and emoji selections.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"processName": "Alo Yoga Ad Campaign",
"productName": "Alo Yoga Clothing and Accessories",
"productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
"targetAudience": "Yoga Enthusiasts",
"type": 1,
"tone": "Professional",
"outputLanguage": "es",
"webSiteUrl": "https://www.aloyoga.com/",
"cta": "Get Sales",
"emojiSelection": 2,
"customRequest": "Mention our patented technology; avoid using the word 'cheap'"
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
GUID
Yes
The unique identifier (GUID) of the application making the request.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
GUID
Yes
The unique identifier (GUID) of the user initiating the request.
2581c740-8e9d-4d63-96bc-5665bb9a646b
processName
string
No
The name of the ad generation process. If empty, it defaults to productName. Max 1000 chars.
Alo Yoga Ad Campaign
productName
string
Yes
The name of the product being advertised. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Alo Yoga Clothing and Accessories
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Alo Yoga offers a wide range of yoga leggings...
targetAudience
string
No
The intended audience for the ad. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Yoga Enthusiasts
type
int
Yes
The type of ad text to generate. See AdTextType. Default: 1 (SharpTechnique).
1
tone
string
No
The tone of the ad text. See AdTextTones. Max 1000 characters.
Professional
outputLanguage
string
Yes
The language of the generated ad text (e.g., en, es, English, Spanish). Max 100 chars.
es
webSiteUrl
string
No
The website URL related to the product. Max 2083 characters.
https://www.aloyoga.com/
cta
string
No
The call-to-action for the ad. Max 1000 chars. Can be fetched as adGoal or cta via /ProductDescription endpoint.
Get Sales
emojiSelection
int
Yes
Emoji usage in the ad text. See AdTextEmojiSelection. Default: 2 (ChosenByAi).
2
customRequest
string
No
Custom instructions for text generation (e.g., specific phrasing). Max 5000 characters.
Mention our patented technology; avoid 'cheap'
Enum: AdTextType
1: SharpTechnique (default)
2: GateFramework
3: LiftMethod
Enum: AdTextTones
Professional
Informal
Friendly
Enum: AdTextEmojiSelection
0: WithEmojis
1: WithoutEmojis
2: ChosenByAi (default)
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/Ads' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'processName="Alo Yoga Ad Campaign"' \
--form 'productName="Alo Yoga Clothing and Accessories"' \
--form 'productDescription="Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there'\''s something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle."' \
--form 'targetAudience="Yoga Enthusiasts"' \
--form 'type="1"' \
--form 'tone="Professional"' \
--form 'outputLanguage="es"' \
--form 'webSiteUrl="https://www.aloyoga.com/"' \
--form 'cta="Get Sales"' \
--form 'emojiSelection="2"' \
--form 'customRequest="Mention our patented technology; avoid using the word '\''cheap'\''"'
HTTP Request
POST /api/v1/Text/Generation/Ads HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="processName"
Alo Yoga Ad Campaign
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Alo Yoga Clothing and Accessories
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"
Yoga Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="type"
1
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"
Professional
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="outputLanguage"
es
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="webSiteUrl"
https://www.aloyoga.com/
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cta"
Get Sales
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="emojiSelection"
2
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="customRequest"
Mention our patented technology; avoid using the word 'cheap'
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a JSON object containing the generated ad texts and metadata:
The unique identifier of the ad text generation process.
102
createdAt
string
The UTC timestamp when the process was created (ISO 8601 format).
2025-03-06T04:31:56.2825674Z
updatedAt
string
The UTC timestamp when the process was last updated (ISO 8601 format).
2025-03-06T04:32:07.2719168Z
adTexts
array
A list of generated ad text objects.
See below
adTexts[].id
int
The unique identifier of the ad text.
1145
adTexts[].value
string
The generated ad text content.
Encuentra tu ajuste perfecto con Alo Yoga 🧘♂️
adTexts[].favorited
bool
Indicates if the ad text has been marked as a favorite.
false
adTexts[].createdAt
string
The UTC timestamp when the ad text was created (ISO 8601 format).
2025-03-06T04:32:07.2718587Z
adTexts[].updatedAt
string
The UTC timestamp when the ad text was last updated (ISO 8601 format).
2025-03-06T04:32:07.2718587Z
adTexts[].conversionScore
string
A score indicating the predicted effectiveness of the ad text (0-100).
91
adTexts[].type
int
The type of ad text, matching the request type. See AdTextType.
1
PUT /api/v1/Text/Generation/Ads
This endpoint updates and regenerates advertising text (ad copy) for an existing ad text generation process identified by its id. It allows modification of product details, target audience, and customization options to produce updated ad texts tailored to specific marketing needs, supporting various text types, tones, languages, and emoji selections.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"id": 103,
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"processName": "Alo Yoga Ad Campaign",
"productName": "Alo Yoga Clothing and Accessories",
"productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
"targetAudience": "Yoga Enthusiasts",
"type": 1,
"tone": "Friendly",
"outputLanguage": "English",
"webSiteUrl": "https://www.aloyoga.com/",
"cta": "Get Sales",
"emojiSelection": 2,
"customRequest": "Mention our patented technology; avoid using the word 'cheap'"
}
Request Parameters
Parameter
Type
Required
Description
Example Value
id
int
Yes
The unique identifier of the ad text generation process to update.
103
applicationId
GUID
Yes
The unique identifier (GUID) of the application making the request.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
GUID
Yes
The unique identifier (GUID) of the user initiating the request.
2581c740-8e9d-4d63-96bc-5665bb9a646b
processName
string
No
The name of the ad generation process. If empty, defaults to productName. Max 1000 chars.
Alo Yoga Ad Campaign
productName
string
Yes
The name of the product being advertised. Max 1000 chars. Can be fetched via /ProductDescription endpoint.
Alo Yoga Clothing and Accessories
productDescription
string
Yes
A detailed description of the product. Max 5000 chars. Can be fetched via /ProductDescription endpoint.
Alo Yoga offers a wide range of yoga leggings...
targetAudience
string
No
The intended audience for the ad. Max 1000 chars. Can be fetched via /ProductDescription endpoint.
Yoga Enthusiasts
type
int
Yes
The type of ad text to generate. See AdTextType. Default: 1 (SharpTechnique).
1
tone
string
No
The tone of the ad text. See AdTextTones. Max 1000 chars.
Friendly
outputLanguage
string
Yes
The language of the generated ad text (e.g., en, es, English, Spanish). Max 100 chars.
English
webSiteUrl
string
No
The website URL related to the product. Max 2083 chars.
https://www.aloyoga.com/
cta
string
No
The call-to-action for the ad. Max 1000 chars. Can be fetched as adGoal or cta via /ProductDescription endpoint.
Get Sales
emojiSelection
int
Yes
Emoji usage in the ad text. See AdTextEmojiSelection. Default: 2 (ChosenByAi).
2
customRequest
string
No
Custom instructions for text generation (e.g., specific phrasing). Max 5000 chars.
Mention our patented technology; avoid 'cheap'
Enum: AdTextType
1: SharpTechnique (default)
2: GateFramework
3: LiftMethod
Enum: AdTextTones
Professional
Informal
Friendly
Enum: AdTextEmojiSelection
0: WithEmojis
1: WithoutEmojis
2: ChosenByAi (default)
Example Requests
cURL
curl --location --request PUT 'https://api.adcreative.ai/api/v1/Text/Generation/Ads' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'id="103"' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'processName="Alo Yoga Ad Campaign"' \
--form 'productName="Alo Yoga Clothing and Accessories"' \
--form 'productDescription="Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there'\''s something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle."' \
--form 'targetAudience="Yoga Enthusiasts"' \
--form 'type="1"' \
--form 'tone="Friendly"' \
--form 'outputLanguage="English"' \
--form 'webSiteUrl="https://www.aloyoga.com/"' \
--form 'cta="Get Sales"' \
--form 'emojiSelection="2"' \
--form 'customRequest="Mention our patented technology; avoid using the word '\''cheap'\''"'
HTTP Request
PUT /api/v1/Text/Generation/Ads HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="id"
103
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="processName"
Alo Yoga Ad Campaign
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Alo Yoga Clothing and Accessories
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"
Yoga Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="type"
1
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"
Friendly
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="outputLanguage"
English
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="webSiteUrl"
https://www.aloyoga.com/
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cta"
Get Sales
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="emojiSelection"
2
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="customRequest"
Mention our patented technology; avoid using the word 'cheap'
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a JSON object containing the updated ad texts and metadata:
The unique identifier of the ad text generation process.
103
createdAt
string
The UTC timestamp when the process was created (ISO 8601 format).
2025-03-06T10:29:59.635468Z
updatedAt
string
The UTC timestamp when the process was last updated (ISO 8601 format).
2025-03-06T10:30:40.7224539Z
adTexts
array
A list of generated ad text objects.
See below
adTexts[].id
int
The unique identifier of the ad text.
1174
adTexts[].value
string
The generated ad text content.
Free Shipping & Returns! Find Your Perfect Fit with Alo Yoga
adTexts[].favorited
bool
Indicates if the ad text has been marked as a favorite.
false
adTexts[].createdAt
string
The UTC timestamp when the ad text was created (ISO 8601 format).
2025-03-06T10:30:40.7224528Z
adTexts[].updatedAt
string
The UTC timestamp when the ad text was last updated (ISO 8601 format).
2025-03-06T10:30:40.7224528Z
adTexts[].conversionScore
string
A score indicating the predicted effectiveness of the ad text (0-100).
96
adTexts[].type
int
The type of ad text, matching the request type. See AdTextType.
1
GET /api/v1/Text/Generation/UserAd
This endpoint retrieves a list of ad text generation processes for a specific user and optionally a specific process ID. It returns detailed information about the process, including generated ad texts, product details, and customization settings such as type, tone, and emoji selection.
Request
The request is sent as a GET request with query parameters:
Request JSON Format
Since this is a GET request, there is no request body. However, the query parameters can be represented as a JSON object for clarity:
A successful response returns a 200 OK status with a JSON array containing the ad text generation processes and their associated ad texts. Below is an example response (shortened for brevity):
[
{
"id": 103,
"type": 1,
"productName": "Alo Yoga Clothing and Accessories",
"productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
"processName": "Alo Yoga Clothing and Accessories",
"websiteUrl": "https://www.aloyoga.com/",
"createdAt": "2025-03-06T10:29:59.635468Z",
"updatedAt": "2025-03-06T10:30:40.722453Z",
"cta": "Get Sales",
"tone": "Friendly",
"outputLanguage": "English",
"targetAudience": "Yoga Enthusiasts",
"emojiSelection": 2,
"adTexts": [
{
"id": 1174,
"value": "Free Shipping & Returns! Find Your Perfect Fit with Alo Yoga",
"favorited": false,
"createdAt": "2025-03-06T10:30:40.722452Z",
"updatedAt": "2025-03-06T10:30:40.722452Z",
"conversionScore": "96",
"type": 1
},
{
"id": 1166,
"value": "Look & Feel Amazing! 🧘♀️",
"favorited": false,
"createdAt": "2025-03-06T10:30:40.722451Z",
"updatedAt": "2025-03-06T10:30:40.722451Z",
"conversionScore": "95",
"type": 1
}
]
}
]
Response Parameters
Parameter
Type
Description
Example Value
id
int
The unique identifier of the ad text generation process.
103
type
int
The type of ad text generated. See AdTextType.
1
productName
string
The name of the product being advertised.
Alo Yoga Clothing and Accessories
productDescription
string
A detailed description of the product.
Alo Yoga offers a wide range of yoga leggings...
processName
string
The name of the ad generation process.
Alo Yoga Clothing and Accessories
websiteUrl
string
The website URL related to the product.
https://www.aloyoga.com/
createdAt
string
The UTC timestamp when the process was created (ISO 8601 format).
2025-03-06T10:29:59.635468Z
updatedAt
string
The UTC timestamp when the process was last updated (ISO 8601 format).
2025-03-06T10:30:40.722453Z
cta
string
The call-to-action for the ad.
Get Sales
tone
string
The tone of the generated ad text. See AdTextTones.
Friendly
outputLanguage
string
The language of the generated ad text.
English
targetAudience
string
The intended audience for the ad.
Yoga Enthusiasts
emojiSelection
int
Emoji usage in the ad text. See AdTextEmojiSelection.
2
adTexts
array
A list of generated ad text objects.
See below
adTexts[].id
int
The unique identifier of the ad text.
1174
adTexts[].value
string
The generated ad text content.
Free Shipping & Returns! Find Your Perfect Fit with Alo Yoga
adTexts[].favorited
bool
Indicates if the ad text has been marked as a favorite.
false
adTexts[].createdAt
string
The UTC timestamp when the ad text was created (ISO 8601 format).
2025-03-06T10:30:40.722452Z
adTexts[].updatedAt
string
The UTC timestamp when the ad text was last updated (ISO 8601 format).
2025-03-06T10:30:40.722452Z
adTexts[].conversionScore
string
A score indicating the predicted effectiveness of the ad text (0-100).
96
adTexts[].type
int
The type of ad text, matching the process type. See AdTextType.
1
Enum: AdTextType
1: SharpTechnique (default)
2: GateFramework
3: LiftMethod
Enum: AdTextTones
Professional
Informal
Friendly
Enum: AdTextEmojiSelection
0: WithEmojis
1: WithoutEmojis
2: ChosenByAi (default)
GET /api/v1/Text/Generation/ApplicationAllAds
This endpoint retrieves all ad text generation processes associated with a specific application ID. It returns detailed information about each process, including generated ad texts, product details, and customization settings such as type, tone, and emoji selection.
Request
The request is sent as a GET request with a query parameter:
Request JSON Format
Since this is a GET request, there is no request body. However, the query parameter can be represented as a JSON object for clarity:
A successful response returns a 200 OK status with a JSON array containing the ad text generation processes and their associated ad texts. Below is a simplified example response with fewer adTexts entries to illustrate the structure:
[
{
"id": 1,
"type": 1,
"productName": "Alo Yoga Clothing and Accessories",
"productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
"processName": "Alo Yoga Clothing and Accessories",
"websiteUrl": "https://www.aloyoga.com/",
"createdAt": "2025-01-23T04:04:15.296926Z",
"updatedAt": "2025-01-23T04:05:53.269815Z",
"cta": "Get Sales",
"tone": "Friendly",
"outputLanguage": "English",
"targetAudience": "Yoga Enthusiasts",
"emojiSelection": 2,
"adTexts": [
{
"id": 19,
"value": "Elevate Your Yoga Style",
"favorited": false,
"createdAt": "2025-01-23T04:05:53.269811Z",
"updatedAt": "2025-01-23T04:05:53.269811Z",
"conversionScore": "93",
"type": 1
},
{
"id": 26,
"value": "Embrace Comfort & Style with Alo Yoga Apparel",
"favorited": false,
"createdAt": "2025-01-23T04:05:53.269812Z",
"updatedAt": "2025-01-23T04:05:53.269812Z",
"conversionScore": "93",
"type": 1
}
]
},
{
"id": 2,
"type": 1,
"productName": "Alo Yoga Clothing and Accessories",
"productDescription": "Alo Yoga offers a wide range of yoga leggings, clothing, and accessories designed for both studio and street wear. Our products combine style and functionality, ensuring that you look great while performing at your best. With options that include leggings, sweatshirts, sports bras, and more, there's something for everyone. Enjoy free shipping and returns on your order, making it easy to find the perfect fit for your active lifestyle.",
"processName": "Alo Yoga Clothing and Accessories",
"websiteUrl": "https://www.aloyoga.com/",
"createdAt": "2025-01-23T04:15:23.328589Z",
"updatedAt": "2025-01-23T04:15:37.471426Z",
"cta": "Get Sales",
"tone": "Professional",
"outputLanguage": "es",
"targetAudience": "Yoga Enthusiasts",
"emojiSelection": 2,
"adTexts": [
{
"id": 41,
"value": "Alo Yoga: Comodidad y estilo en cada pose",
"favorited": false,
"createdAt": "2025-01-23T04:15:37.471355Z",
"updatedAt": "2025-01-23T04:15:37.471355Z",
"conversionScore": "95",
"type": 1
},
{
"id": 45,
"value": "Ropa de yoga Alo: Funcionalidad sin perder estilo",
"favorited": false,
"createdAt": "2025-01-23T04:15:37.471357Z",
"updatedAt": "2025-01-23T04:15:37.471357Z",
"conversionScore": "94",
"type": 1
}
]
}
]
Response Parameters
Parameter
Type
Description
Example Value
id
int
The unique identifier of the ad text generation process.
1
type
int
The type of ad text generated. See AdTextType.
1
productName
string
The name of the product being advertised.
Alo Yoga Clothing and Accessories
productDescription
string
A detailed description of the product.
Alo Yoga offers a wide range of yoga leggings...
processName
string
The name of the ad generation process.
Alo Yoga Clothing and Accessories
websiteUrl
string
The website URL related to the product.
https://www.aloyoga.com/
createdAt
string
The UTC timestamp when the process was created (ISO 8601 format).
2025-01-23T04:04:15.296926Z
updatedAt
string
The UTC timestamp when the process was last updated (ISO 8601 format).
2025-01-23T04:05:53.269815Z
cta
string
The call-to-action for the ad.
Get Sales
tone
string
The tone of the generated ad text. See AdTextTones.
Friendly
outputLanguage
string
The language of the generated ad text.
English
targetAudience
string
The intended audience for the ad.
Yoga Enthusiasts
emojiSelection
int
Emoji usage in the ad text. See AdTextEmojiSelection.
2
adTexts
array
A list of generated ad text objects.
See below
adTexts[].id
int
The unique identifier of the ad text.
19
adTexts[].value
string
The generated ad text content.
Elevate Your Yoga Style
adTexts[].favorited
bool
Indicates if the ad text has been marked as a favorite.
false
adTexts[].createdAt
string
The UTC timestamp when the ad text was created (ISO 8601 format).
2025-01-23T04:05:53.269811Z
adTexts[].updatedAt
string
The UTC timestamp when the ad text was last updated (ISO 8601 format).
2025-01-23T04:05:53.269811Z
adTexts[].conversionScore
string
A score indicating the predicted effectiveness of the ad text (0-100).
93
adTexts[].type
int
The type of ad text, matching the process type. See AdTextType.
1
Enum: AdTextType
1: SharpTechnique (default)
2: GateFramework
3: LiftMethod
Enum: AdTextTones
Professional
Informal
Friendly
Enum: AdTextEmojiSelection
0: WithEmojis
1: WithoutEmojis
2: ChosenByAi (default)
GET /api/v1/Text/Generation/ProductDescription
This endpoint retrieves product-related information (e.g., product name, description, target audience) by scraping content from a specified website URL. It supports customization options such as preferred language and an advanced scraping mode.
Request
The request is sent as a GET request with query parameters:
Request JSON Format
Since this is a GET request, there is no request body. However, the query parameters can be represented as a JSON object for clarity:
A successful response returns a 200 OK status with a JSON object containing the extracted product-related information:
{
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, serving authentic espresso Italiano. Our espresso is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialetti moka pots. Enjoy a cozy atmosphere where you can take a break from your day with our delicious offerings, including cappuccinos, focaccia sandwiches, and more. We pride ourselves on the quality of our coffee, adhering to the 5 ‘M’ rule for a perfect brew: The Blend, The Grind, The Machine, The Maintenance, and The Barista’s Hand.",
"targetAudience": "Coffee enthusiasts",
"adGoal": "Get Store Visits",
"language": "English",
"cta": "Visit us today!"
}
Response Parameters
Parameter
Type
Description
Example Value
productName
string
The name of the product extracted from the website. May be null if not found.
Caffettiera
productDescription
string
The detailed description of the product extracted from the website. May be null if not found.
Caffettiera is a 90’s inspired Italian bar...
targetAudience
string
The target audience information extracted from the website. May be null if not found.
Coffee enthusiasts
adGoal
string
The advertising goal extracted from the website content. May be null if not found.
Get Store Visits
language
string
The language identified from the website content. May be null if not identified.
English
cta
string
The call-to-action (CTA) text extracted from the website content. May be null if not found.
Visit us today!
POST /api/v1/Text/Generation/AdStrategies
This endpoint generates a list of advertising strategies based on provided product details, target audience, and advertising goals. Parameters such as productName, productDescription, targetAudience, and adGoal can be fetched from the response of the GET /api/v1/Text/Generation/ProductDescription endpoint.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
"targetAudience": "Coffee Enthusiasts",
"adGoal": "Get Store Visits"
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
Guid
Yes
The unique identifier (GUID) of the application making the request. Must be a valid GUID string.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
Guid
Yes
The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.
2581c740-8e9d-4d63-96bc-5665bb9a646b
productName
string
Yes
The name of the product being advertised. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera is a 90’s inspired Italian bar...
targetAudience
string
Yes
The intended audience for the ad. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Coffee Enthusiasts
adGoal
string
Yes
The advertising goal for the campaign. Max 1000 characters. Can be fetched via /ProductDescription endpoint as adGoal or cta.
Get Store Visits
currentStrategies
array
No
A list of current strategies already in use (optional). Each item is a string.
["Limited Time Offer", "Exclusive Discount"]
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/AdStrategies' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'targetAudience="Coffee Enthusiasts"' \
--form 'adGoal="Get Store Visits"'
HTTP Request
POST /api/v1/Text/Generation/AdStrategies HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"
Coffee Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="adGoal"
Get Store Visits
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a JSON array containing the generated ad strategies:
[
{
"adStrategyShortName": "Limited Time Offer",
"rationale": "A 'Limited Time Offer' creates urgency among coffee enthusiasts, encouraging them to visit the Italian-inspired bar for a unique espresso experience before the offer expires.",
"fontAwesomeIcon": "fa-solid fa-clock"
},
{
"adStrategyShortName": "Exclusive Discount",
"rationale": "Offering an 'Exclusive Discount' incentivizes coffee lovers to experience the authentic Italian coffee and snacks at Caffettiera, driving increased foot traffic to the location.",
"fontAwesomeIcon": "fa-solid fa-tag"
},
{
"adStrategyShortName": "Buy One Get One Free",
"rationale": "A 'Buy One Get One Free' offer on espresso drinks encourages coffee enthusiasts to visit Caffettiera with friends, boosting store visits and enhancing the social coffee experience.",
"fontAwesomeIcon": "fa-solid fa-mug-hot"
},
{
"adStrategyShortName": "Free Gift with Purchase",
"rationale": "Providing a 'Free Gift with Purchase' such as an Italian snack motivates coffee enthusiasts to visit Caffettiera to enjoy both the coffee and a delightful treat, enhancing the overall experience.",
"fontAwesomeIcon": "fa-solid fa-gift"
}
]
Response Parameters
Parameter
Type
Description
Example Value
adStrategyShortName
string
The short name of the advertising strategy.
Limited Time Offer
rationale
string
The rationale or reasoning behind the strategy.
A 'Limited Time Offer' creates urgency...
fontAwesomeIcon
string
The FontAwesome icon representing the strategy.
fa-solid fa-clock
POST /api/v1/Text/Generation/AdCopies
This endpoint generates ad copies consisting of headlines, punchlines, and call-to-actions based on provided product details, strategy, tone, and other customization options. The strategy parameter can be fetched as adStrategyShortName from the POST /api/v1/Text/Generation/AdStrategies endpoint.
Additionally, this endpoint serves as an alternative to provide diverse headlines, punchlines, and actiontext (as call-to-actions) for the following image generation endpoints before image creation:
POST /api/v1/Image/Generation/AdCreativesByKind
POST /api/v1/Image/Editing/AdCreativesByTasks
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
"strategy": "Limited Time Offer",
"cta": "Visit Us Today!",
"outputLanguage": "en",
"tone": "Professional",
"targetAudience": "Coffee Enthusiasts",
"isLongHeadline": true
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
Guid
Yes
The unique identifier (GUID) of the application making the request. Must be a valid GUID string.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
Guid
Yes
The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.
2581c740-8e9d-4d63-96bc-5665bb9a646b
productName
string
Yes
The name of the product being advertised. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera is a 90’s inspired Italian bar...
strategy
string
No
The advertising strategy to apply. Max 2000 characters. Can be fetched as adStrategyShortName from /AdStrategies endpoint.
Limited Time Offer
cta
string
Yes
The call-to-action text for the ad. Max 1000 characters. Can be fetched as adGoal or cta via /ProductDescription endpoint.
Visit Us Today!
outputLanguage
string
Yes
The language of the generated ad copy (e.g., "en", "English", "es", "Spanish"). Max 100 characters.
en
tone
string
Yes
The tone of the ad copy (e.g., "Professional", "Informal", "Friendly"). Max 1000 characters. See AdTextTones.
Professional
targetAudience
string
Yes
The intended audience for the ad. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Coffee Enthusiasts
isLongHeadline
bool
Yes
Determines if headlines should be long and detailed (true) or short and concise (false, typically 13-17 words).
true
Enum: AdTextTones
Professional
Informal
Friendly
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Generation/AdCopies' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'strategy="Limited Time Offer"' \
--form 'cta="Visit Us Today!"' \
--form 'outputLanguage="en"' \
--form 'tone="Professional"' \
--form 'targetAudience="Coffee Enthusiasts"' \
--form 'isLongHeadline="true"'
HTTP Request
POST /api/v1/Text/Generation/AdCopies HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="strategy"
Limited Time Offer
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cta"
Visit Us Today!
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="outputLanguage"
en
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"
Professional
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="targetAudience"
Coffee Enthusiasts
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="isLongHeadline"
true
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a JSON object containing the generated ad copies, including headlines, punchlines, and call-to-actions. Below is a shortened example for brevity:
{
"headlines": [
"Craving Authentic Italian Coffee in Montreal?",
"Want a Taste of Italy in Every Sip?",
"Seeking an Authentic Italian Coffee Experience in Montreal’s Golden Square Mile?",
"Looking for Classic Bialetti-Brewed Coffee in a Cozy Italian Bar Setting?"
],
"punchlines": [
"Taste Italy in Every Sip",
"Discover Espresso Perfection",
"Indulge in 90's Italian Charm",
"Experience La SanMarco Magic"
],
"callToActions": [
{
"cta": "Taste Italy Today!",
"fontAwesomeIcon": "fa-solid fa-coffee"
},
{
"cta": "Sip Authentic Espresso!",
"fontAwesomeIcon": "fa-solid fa-mug-hot"
},
{
"cta": "Visit for Focaccia!",
"fontAwesomeIcon": "fa-solid fa-bread-slice"
},
{
"cta": "Discover Caffettiera!",
"fontAwesomeIcon": "fa-solid fa-location-dot"
}
]
}
Response Parameters
Parameter
Type
Description
Example Value
headlines
array
A collection of generated headlines. Each item is a string.
"Craving Authentic Italian Coffee in Montreal?"
punchlines
array
A collection of generated punchlines. Each item is a string.
"Taste Italy in Every Sip"
callToActions
array
A collection of generated call-to-action objects.
See below
callToActions[].cta
string
The call-to-action text.
"Taste Italy Today!"
callToActions[].fontAwesomeIcon
string
The FontAwesome icon associated with the call-to-action.
"fa-solid fa-coffee"
POST /api/v1/Text/Craft/ChangeSentiment
This endpoint changes the sentiment of a given text (e.g., a headline) based on provided product details and customization options like tone and language.
It can be used to optimize outputs from the POST /api/v1/Text/Generation/AdCopies endpoint, refining headlines, punchlines, or call-to-actions to better suit the desired sentiment.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"headLine": "Craving true Italian espresso in Montreal's heart?",
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
"tone": "Informal"
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
Guid
Yes
The unique identifier (GUID) of the application making the request. Must be a valid GUID string.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
Guid
Yes
The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.
2581c740-8e9d-4d63-96bc-5665bb9a646b
headLine
string
Yes
The text (e.g., headline) to change sentiment for. Max 500 characters. Can be fetched from /AdCopies endpoint as headlines.
Craving true Italian espresso in Montreal's heart?
productName
string
Yes
The name of the product. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera is a 90’s inspired Italian bar...
tone
string
No
The desired tone of the text (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.
Informal
language
string
No
The language of the text (e.g., "en", "English"). Max 10 characters.
en
textLimit
int
No
The character limit for the output text. Must be between 1 and 1000. Defaults to 40.
40
Enum: AdTextTones
Professional
Informal
Friendly
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/ChangeSentiment' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'tone="Informal"'
HTTP Request
POST /api/v1/Text/Craft/ChangeSentiment HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"
Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tone"
Informal
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a single string representing the text with its sentiment changed:
"Espresso vibes in Montreal?"
Response Parameters
Parameter
Type
Description
Example Value
(response)
string
The text with its sentiment changed based on the provided inputs and tone.
"Espresso vibes in Montreal?"
POST /api/v1/Text/Craft/MakeShorten
This endpoint shortens a given headline based on provided product details and customization options like tone, language, and a text limit.
It can be used to optimize outputs from the POST /api/v1/Text/Generation/AdCopies endpoint, refining headlines to be more concise while preserving their core message.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"headLine": "Craving true Italian espresso in Montreal's heart?",
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
Guid
Yes
The unique identifier (GUID) of the application making the request. Must be a valid GUID string.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
Guid
Yes
The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.
2581c740-8e9d-4d63-96bc-5665bb9a646b
headLine
string
Yes
The headline to shorten. Max 500 characters. Can be fetched from /AdCopies endpoint as headlines.
Craving true Italian espresso in Montreal's heart?
productName
string
Yes
The name of the product. Max 1000 characters. Can be fetched via /ProductDescription enpoint.
Caffettiera
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera is a 90’s inspired Italian bar...
tone
string
No
The desired tone of the text (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.
Informal
language
string
No
The language of the text (e.g., "en", "English"). Max 10 characters.
en
textLimit
int
No
The character limit for the shortened text. Must be between 1 and 1000. Defaults to 40.
40
Enum: AdTextTones
Professional
Informal
Friendly
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/MakeShorten' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."'
HTTP Request
POST /api/v1/Text/Craft/MakeShorten HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"
Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a single string representing the shortened headline. (Note: The original input did not provide an example response, so an assumed example is included based on the endpoint’s purpose):
"Craving Italian espresso?"
Response Parameters
Parameter
Type
Description
Example Value
(response)
string
The shortened version of the provided headline, adhering to the text limit.
"Craving Italian espresso?"
POST /api/v1/Text/Craft/Translate
This endpoint translates a given text (e.g., a headline) into a specified target language based on provided product details and customization options.
It can be used to translate outputs from the POST /api/v1/Text/Generation/AdCopies endpoint, such as headlines, punchlines, or call-to-actions, into different languages for broader reach.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"headLine": "Craving true Italian espresso in Montreal's heart?",
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.",
"language": "Spanish"
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
Guid
Yes
The unique identifier (GUID) of the application making the request. Must be a valid GUID string.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
Guid
Yes
The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.
2581c740-8e9d-4d63-96bc-5665bb9a646b
headLine
string
Yes
The text (e.g., headline) to translate. Max 500 characters. Can be fetched from /AdCopies endpoint as headlines.
Craving true Italian espresso in Montreal's heart?
productName
string
Yes
The name of the product. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera is a 90’s inspired Italian bar...
tone
string
No
The desired tone of the text (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.
Informal
language
string
No
The target language for translation (e.g., "en", "English", "es", "Spanish"). Max 10 characters. If omitted, translation may not occur as expected.
Spanish
textLimit
int
No
The character limit for the translated text. Must be between 1 and 1000. Defaults to 40.
40
Enum: AdTextTones
Professional
Informal
Friendly
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/Translate' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."' \
--form 'language="Spanish"'
HTTP Request
POST /api/v1/Text/Craft/Translate HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"
Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="language"
Spanish
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a single string representing the translated text:
"¿Deseas espresso italiano en Montreal?"
Response Parameters
Parameter
Type
Description
Example Value
(response)
string
The translated version of the provided text in the specified target language.
"¿Deseas espresso italiano en Montreal?"
POST /api/v1/Text/Craft/CreateVariations
This endpoint creates multiple variations of a given headline based on provided product details and customization options like tone and language.
It can be used to vary outputs from the POST /api/v1/Text/Generation/AdCopies endpoint, generating alternative headlines, punchlines, or call-to-actions for greater diversity.
Request
The request is sent as multipart/form-data with the following parameters:
Request JSON Format
Below is an example of how the request parameters would look if represented as a JSON object (though the actual request uses multipart/form-data):
{
"applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
"userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
"headLine": "Craving true Italian espresso in Montreal's heart?",
"productName": "Caffettiera",
"productDescription": "Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."
}
Request Parameters
Parameter
Type
Required
Description
Example Value
applicationId
Guid
Yes
The unique identifier (GUID) of the application making the request. Must be a valid GUID string.
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
userId
Guid
Yes
The unique identifier (GUID) of the user initiating the request. Must be a valid GUID string.
2581c740-8e9d-4d63-96bc-5665bb9a646b
headLine
string
Yes
The headline to create variations for. Max 500 characters. Can be fetched from /AdCopies endpoint as headlines.
Craving true Italian espresso in Montreal's heart?
productName
string
Yes
The name of the product. Max 1000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera
productDescription
string
Yes
A detailed description of the product. Max 5000 characters. Can be fetched via /ProductDescription endpoint.
Caffettiera is a 90’s inspired Italian bar...
tone
string
No
The desired tone of the variations (e.g., "Professional", "Informal", "Friendly"). Max 500 characters. See AdTextTones.
Informal
language
string
No
The language of the variations (e.g., "en", "English"). Max 10 characters.
en
textLimit
int
No
The character limit for each variation. Must be between 1 and 1000. Defaults to 40.
40
Enum: AdTextTones
Professional
Informal
Friendly
Example Requests
cURL
curl --location 'https://api.adcreative.ai/api/v1/Text/Craft/CreateVariations' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4' \
--header 'x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9' \
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \
--form 'headLine="Craving true Italian espresso in Montreal'\''s heart?"' \
--form 'productName="Caffettiera"' \
--form 'productDescription="Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting."'
HTTP Request
POST /api/v1/Text/Craft/CreateVariations HTTP/1.1
Host: api.adcreative.ai
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
x-api-key: a1c3b5d7e9f6a8c4d2e9b3f7c5a9b1e4
x-api-secret: f5c6a7b8e9d4f1a3c7b6e8f3a9d5c2e7f8a6c1b9e7f3d5a4c6e9f8b2a7c5e1d9
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="applicationId"
4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"
2581c740-8e9d-4d63-96bc-5665bb9a646b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="headLine"
Craving true Italian espresso in Montreal's heart?
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productName"
Caffettiera
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="productDescription"
Caffettiera is a 90’s inspired Italian bar located in Montreal’s Golden Square Mile, offering a unique espresso experience. Our coffee is roasted in Italy and brewed to order using La SanMarco Leva machines and classic Bialettis, ensuring each cup is crafted to perfection. We serve a variety of traditional Italian beverages and snacks, including espresso Italiano, cappuccinos, and delicious focaccia sandwiches. Visit us daily from 7h30 to 18h for an authentic taste of Italy in a cozy setting.
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
Response JSON Format
A successful response returns a 200 OK status with a JSON array containing multiple variations of the provided headline:
[
"Italian Espresso in Montreal!",
"Savor Italy's Espresso Here!",
"Authentic Italian Coffee Awaits!",
"Discover Italian Espresso Bliss!",
"Espresso Italiano in Montreal!"
]
Response Parameters
Parameter
Type
Description
Example Value
(response)
array
A list of string variations of the provided headline, adhering to the text limit and tone.
"Italian Espresso in Montreal!"
Common Error Responses in Ad Text Generation API
This section outlines the common error responses (excluding 200 OK) that may occur across endpoints in the Ad Text Generation API feature. These errors include authorization issues (401 Unauthorized), client-side request issues (400 Bad Request), and server-side failures (500 Internal Server Error), along with validation errors. Error messages are categorized into business: and engine: keys:
business: Represents errors originating from the business logic layer, providing user-friendly messages about why the request failed (e.g., missing resources, invalid inputs).
engine: Represents errors from the engine layer, offering technical details for developers to debug underlying issues (e.g., exceptions, service failures).
These responses are designed to help customers understand issues and assist developers in troubleshooting integrations.
Authorization Error Response
HTTP Status Code:401 Unauthorized
Description: This error occurs when the request lacks valid authentication credentials. Common causes include a missing or invalid API token (x-api-key or x-api-secret) or an ApplicationId that does not match any registered application in the token.
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-d091dbc705803deaa77bd4d9abc17607-d1c93b4c70053719-00"
}
}
Guidance: Ensure the x-api-key and x-api-secret headers are included and valid. Verify that the ApplicationId matches the one associated with your API credentials.
Bad Request Error Response
HTTP Status Code:400 Bad Request
Description: This error indicates that the request is malformed, contains invalid data, or fails validation. It can stem from missing required fields, incorrect parameter formats, or business logic failures (e.g., no data found for the request). Below are several examples showcasing different scenarios.
Example 1: Validation Error (Single Field)
Description: Returned when a single parameter has an invalid value.
{
"errors": {
"type": [
"The value '99' is invalid."
]
},
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-5e74736b3b7a4e64fb6fbc093c71bdda-c314cf7facb19565-00"
}
Guidance: Check the parameter named type and ensure it conforms to the expected format or range (e.g., an enum value).
Example 2: Validation Error (Multiple Fields)
Description: Returned when multiple required fields are missing or invalid.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Type": [
"The value '' is invalid."
],
"ProductName": [
"ProductName is required."
],
"EmojiSelection": [
"The value '' is invalid."
],
"OutputLanguage": [
"The OutputLanguage field is required."
],
"ProductDescription": [
"ProductDescription is required."
]
},
"traceId": "00-8dd517f6b559ac36115bc9711d7d7bb0-0071e9856eba9e87-00"
}
Guidance: Review the request body or parameters (e.g., multipart/form-data) and provide valid values for all required fields. Refer to the endpoint’s documentation for expected formats.
Example 3: Business and Engine Error (Resource Not Found)
Description: Returned when a specific resource cannot be found, with details from both business and engine layers.
{
"errors": {
"engine: Generation/Ads": [
"An unexpected error occurred while getting the ad text generation processes: No Ad Text Generation Process was not found for the AdTextGeneratorProcessId 104 or the User: 2581c740-8e9d-4d63-96bc-5665bb9a646b or the Application: "
],
"business: Generation/UserAd": [
"Bad request error occurred while getting Ad Text Generation Process for the AdTextGeneratorProcessId: 104 or the User: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
]
},
"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-72523eede63262ad12f4ea0763b3b28f-bb0635ce1b353533-00"
}
}
Guidance: Verify the AdTextGeneratorProcessId, UserId, and ApplicationId. The resource may not exist or the IDs may be incorrect.
Example 4: Business and Engine Error (Product Description Not Found)
Description: Returned when a product description cannot be retrieved for the given URL.
{
"errors": {
"engine: Generation/ProductDescription": [
"An unexpected error occurred while getting the product description: No product description was found for the URL: https://www.aloyoga/"
],
"business: Generation/ProductDescription": [
"Bad request error occurred while getting product description for the Application: d5eabbb8-c0f6-4640-94fd-3566edad499f and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b with the Url: https://www.aloyoga"
]
},
"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-5715acbbbe9bcdbb34aa3ada818d31bd-c9a07f0747128841-00"
}
}
Guidance: Ensure the provided URL is valid and contains extractable product information. Check the ApplicationId and UserId as well.
Example 5: Business and Engine Error (Invalid URL Format)
Description: Returned when the URL format is invalid.
{
"errors": {
"engine: Generation/ProductDescription": [
"An unexpected error occurred while getting the product description: Invalid URL format. (Parameter 'url')"
],
"business: Generation/ProductDescription": [
"Bad request error occurred while getting product description for the Application: 4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6 and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b with the Url: ww.caffettier"
]
},
"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-cc89fdef1bc10c6cd8ecf0e3bdb0b5ce-5d0c5c161f603546-00"
}
}
Guidance: Correct the URL format (e.g., include https:// and a valid domain). The example ww.caffettier is malformed.
Example 6: Validation Error (Invalid GUIDs)
Description: Returned when UserId or ApplicationId are not valid GUIDs.
{
"errors": {
"userId": [
"The value '2581c740-8e9d-4d63-96bc-5665bb9a6' is not valid for UserId."
],
"applicationId": [
"The value 'c740-8e9d-4d63-96bc-5665bb9a646b' is not valid for ApplicationId."
]
},
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-f96e34aa0aa1c80f1478bd591f317670-379ffdb0c0d6913a-00"
}
Guidance: Ensure UserId and ApplicationId are valid GUIDs (e.g., 2581c740-8e9d-4d63-96bc-5665bb9a646b). Partial or malformed GUIDs are not accepted.
Internal Server Error Response
HTTP Status Code:500 Internal Server Error
Description: This error indicates an unexpected server-side failure, such as an unhandled exception or service issue. It typically includes both business: and engine: messages for context and debugging.
Response Body:
{
"errors": {
"business:": [
"An unexpected error occurred while processing the request for the Application: 4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6 and User: 2581c740-8e9d-4d63-96bc-5665bb9a646b for the Product: Caffettiera"
],
"engine:": [
"Internal service error: Unable to process request."
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
"title": "An unexpected error occurred.",
"status": 500,
"detail": null,
"instance": null,
"extensions": {
"traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
}
}
Guidance: This is a server-side issue. Retry the request later. If the problem persists, contact support with the traceId for assistance in diagnosing the issue.
General Notes on Error Responses
TraceId: Each error includes a unique traceId in the extensions object (or top-level for some 400 responses) to help track and debug issues. Provide this ID when contacting support.
Business vs. Engine Errors:
business: messages are user-facing, explaining what went wrong in a high-level context (e.g., "ProductName is required").
engine: messages are technical, aimed at developers, detailing the underlying issue (e.g., "Invalid URL format").
HTTP Standards: The type field links to RFC 7231 or RFC 9110 sections for HTTP status code definitions, ensuring compliance with industry standards.
Validation Errors: For 400 Bad Request, validation errors list specific fields and issues. Check the endpoint’s documentation for required fields and formats.
Contact Support: For persistent 500 errors or unclear 400/401 issues, use the traceId to report the problem to the support team.
