TikTok Ads Write
Add a new ad to an existing TikTok ad group
POST https://api.adspirer.ai/api/v1/tools/add_tiktok_ad/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
adgroup_id | string required | Existing TikTok ad group ID to add the ad to |
ad_text | string required | Ad text (1-100 characters). |
landing_page_url | string required | Landing page URL (must be HTTPS). |
ad_name | string optional | Ad name. Auto-generated if not provided. |
ad_format | string optional | Ad format: SINGLE_IMAGE, SINGLE_VIDEO. Default: SINGLE_IMAGE. default: "SINGLE_IMAGE" |
display_name | string optional | Brand name (max 40 chars). |
call_to_action | string optional | CTA button: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, CONTACT_US, APPLY_NOW, etc. |
image_ids | array optional | TikTok image IDs from upload_tiktok_images (for SINGLE_IMAGE). |
image_urls | array optional | Public image URLs (HTTPS) — auto-uploaded to TikTok. Use this instead of image_ids for convenience. |
video_id | string optional | TikTok video ID (for SINGLE_VIDEO format). |
identity_id | string optional | Advertiser identity ID. Auto-resolved if not provided. |
identity_type | string optional | Identity type: CUSTOMIZED_USER, BC_AUTH_TT, TT_USER. Auto-resolved if not provided. |
tiktok_item_id | string optional | TikTok organic post ID for Spark Ads (boost existing TikTok posts as ads). |
card_id | string optional | Carousel card ID. |
card_type | string optional | Card type: IMAGE or PRODUCT. |
advertiser_id | string optional | TikTok advertiser ID (optional). |
{
"arguments": {
"adgroup_id": "string",
"ad_text": "string",
"landing_page_url": "https://example.com",
"ad_name": "string",
"ad_format": "SINGLE_IMAGE",
"display_name": "string",
"call_to_action": "string",
"image_ids": [
"string"
],
"image_urls": [
"string"
]
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for add_tiktok_ad)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "add_tiktok_ad"
}
{
"success": false,
"error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n - Acme Holdings (ad_account_id=\"act_123456789\")\n - Acme EU (ad_account_id=\"act_987654321\")",
"is_error": true,
"tool": "add_tiktok_ad"
}
{
"success": false,
"error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
"is_error": true,
"tool": "add_tiktok_ad",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
Interactive: Swagger UI
Machine-readable: OpenAPI 3.1 spec · llms-full.txt
More tools: TikTok Ads · All tools
Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai