Appearance
ai-ads
5 endpoints.
POST /api/v1/ai-ads/generate/{account_id}
Generate
Generate an ad image (and optionally copy) from a prompt — preview only.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"prompt": {
"type": "string",
"title": "Prompt"
},
"with_copy": {
"type": "boolean",
"title": "With Copy",
"default": true
},
"aspect_ratio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Aspect Ratio"
}
},
"type": "object",
"required": [
"prompt"
],
"title": "GenerateRequest"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/ai-ads/chat/{account_id}
Chat
Conversational image generation / editing turn.
Generates a fresh ad image from the message, or — when input_images are supplied — edits/combines them per the message. Preview only; nothing is sent to Meta until the user continues to ad setup.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"message": {
"type": "string",
"title": "Message",
"default": ""
},
"input_images": {
"items": {
"type": "string"
},
"type": "array",
"title": "Input Images",
"default": []
},
"with_copy": {
"type": "boolean",
"title": "With Copy",
"default": false
},
"aspect_ratio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Aspect Ratio"
},
"verbatim": {
"type": "boolean",
"title": "Verbatim",
"default": false
},
"image_labels": {
"items": {
"type": "string"
},
"type": "array",
"title": "Image Labels",
"default": []
}
},
"type": "object",
"title": "ChatRequest",
"description": "One turn of the AI Ad Generator chat.\n\n`input_images` are the images to use as the base/context for this turn — the\nfrontend sends the current working image for edits, plus any files the user\njust attached. Empty means a fresh text-to-image generation.\n\n`aspect_ratio` (e.g. \"4:5\") forces the output shape; carried across edits so a\nportrait ad stays portrait while it's refined.\n\n`verbatim` sends `message` to the model exactly as written, skipping the generic\nad-steering nudges — set by the guided builder, whose prompt is a complete brief.\n\n`image_labels` is an optional per-image instruction, aligned by index with\n`input_images`. Each is placed right before its image so the model binds the\ninstruction (e.g. \"this is the footer logo — reproduce pixel-perfect\") to the\nactual pixels. Falls back to a plain \"Image N:\" marker when absent."
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/ai-ads/pricing-research/{account_id}
Pricing Research
Web-research 3 competitor prices for the described offering + the average.
Powers the "Average of 3 Competitor Prices" pricing strategy: the AI does real web research (Google Search grounding), returns each competitor's price and source, and the average is computed server-side from the parsed amounts.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"description": {
"type": "string",
"title": "Description"
},
"currency": {
"type": "string",
"title": "Currency",
"default": "ZAR"
}
},
"type": "object",
"required": [
"description"
],
"title": "PricingResearchRequest"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/ai-ads/target-suggestions/{account_id}
Target Suggestions
Suggest Facebook detailed-targeting audiences for the described ad.
The AI infers candidate interest/behaviour terms from the brief, each is looked up against Meta's live targeting search (so audience sizes are real), and the response pre-selects the top 3 plus a fuller option list to choose from. Selected targets carry into the Create Ad wizard's ad set targeting.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"description": {
"type": "string",
"title": "Description"
}
},
"type": "object",
"required": [
"description"
],
"title": "TargetSuggestRequest"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/ai-ads/upload-generated/{account_id}
Upload Generated
Upload a previously-generated image to Meta; returns its hash + URL.
Mirrors /creatives/upload-image but takes base64 instead of a file upload, so the image the user already previewed is the exact one that gets published.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"image_b64": {
"type": "string",
"title": "Image B64"
},
"filename": {
"type": "string",
"title": "Filename",
"default": "ai-ad.png"
}
},
"type": "object",
"required": [
"image_b64"
],
"title": "UploadGeneratedRequest"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}