Available Tools

Complete reference for all 22 MCP tools available through Adsumo's MCP server.

Video Generation

generate_ai_video

Generate an AI video using Sora 2, Veo 3.1, or Kling 2.6. Returns a generation_id to poll with get_generation.

Parameter	Type	Required	Description
`model`	string	Yes	`sora-2`, `sora-2-pro`, `veo-3.1`, `veo-3.1-fast`, or `kling-2.6`
`prompt`	string	Yes	Text description of the video to generate
`duration`	integer	Yes	Duration in seconds. Sora 2: 4, 8, 12, 16, 20. Veo 3.1: 4, 6, 8. Kling 2.6: 5, 10
`aspect_ratio`	string	Yes	Sora 2: `16:9`, `9:16`. Veo 3.1: `16:9`, `9:16`, `auto`. Kling 2.6: `16:9`, `9:16`, `1:1`
`resolution`	string	No	Veo 3.1 only: `720p`, `1080p`, `4k` (default `720p`)
`reference_image_url`	string	No	URL of a reference image
`hd`	boolean	No	HD output for Sora 2 (default `false`)
`generate_audio`	boolean	No	Generate audio track (Veo 3.1 default `true`, Kling 2.6 default `false`)
`template`	boolean	No	Save as a template (default `false`)
`template_type`	string	No	Template category if saving as template
`first_frame_image_url`	string	No	Veo 3.1: URL for the first frame image
`last_frame_image_url`	string	No	Veo 3.1: URL for the last frame image
`reference_image_urls`	string[]	No	Veo 3.1: Array of reference image URLs

Example response:

JSON

{
  "generation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "ai-video",
  "status": "processing"
}

generate_talking_avatar

Generate a lip-sync avatar video from an existing voiceover. Call generate_voiceover first to get a voiceover_id.

Parameter	Type	Required	Description
`avatar_id`	string	Yes	ID of the avatar to use
`avatar_type`	string	Yes	`platform`, `custom`, or `product`
`voiceover_id`	string	Yes	UUID of a completed voiceover
`lipsync_model`	string	No	`lipsync-2.0` or `heygen-avatar4` (default `heygen-avatar4`)
`heygen_settings.talking_style`	string	No	`stable` or `expressive`
`heygen_settings.resolution`	string	No	`720p` or `1080p`
`heygen_settings.aspect_ratio`	string	No	`9:16` or `16:9`

Example response:

JSON

{
  "generation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "talking-avatar",
  "status": "processing"
}

generate_swap_avatar

Swap a face onto an existing video. Provide either an image_url or avatar_id + avatar_type.

Parameter	Type	Required	Description
`video_url`	string	Yes	URL of the source video
`mode`	string	Yes	`standard` or `pro`
`duration`	number	Yes	Video duration in seconds (1--30)
`width`	integer	Yes	Video width in pixels
`height`	integer	Yes	Video height in pixels
`image_url`	string	No	URL of the face image (alternative to avatar_id)
`avatar_id`	string	No	Avatar ID (use with avatar_type)
`avatar_type`	string	No	`platform`, `custom`, or `product`

Example response:

JSON

{
  "generation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "swap-avatar",
  "status": "processing"
}

localize_video

Translate and dub a video into another language.

Parameter	Type	Required	Description
`video_url`	string	Yes	URL of the source video
`mode`	string	Yes	`speed` or `precision`
`output_language`	string	Yes	Target language (e.g., `es`, `fr`, `de`)
`duration`	number	Yes	Video duration in seconds (1--120)
`width`	integer	Yes	Video width in pixels
`height`	integer	Yes	Video height in pixels
`translate_audio_only`	boolean	No	Only translate audio, keep original video
`speaker_num`	integer	No	Number of speakers in the video
`enable_dynamic_duration`	boolean	No	Allow output duration to differ from input

Example response:

JSON

{
  "generation_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "type": "localize",
  "status": "processing"
}

edit_video

Apply AI edits to a video (captions, effects). Provide either a video_url or a generation_id of a completed video.

Parameter	Type	Required	Description
`template_id`	string	Yes	Caption/editing template ID
`video_url`	string	No	URL of the video to edit (alternative to generation_id)
`generation_id`	string	No	UUID of a completed AI video generation
`language`	string	No	Language code (default `en`)
`auto_approve`	boolean	No	Auto-approve edits (default `true`)

Example response:

JSON

{
  "generation_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "type": "video-edit",
  "status": "processing",
  "credits_used": 5
}

Image Generation

generate_image

Generate product image ads from a text prompt.

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description of the image to generate
`model`	string	Yes	`fast` or `pro`
`aspect_ratio`	string	Yes	`21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, or `9:16`
`quantity`	integer	No	Number of images (1--8, default 1)
`resolution`	string	No	`1k`, `2k`, or `4k` (default `1k`)

Example response:

JSON

{
  "generation_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "type": "text-to-image",
  "status": "processing",
  "quantity": 4,
  "credits_used": 8
}

edit_image

Edit or remix images using reference images and a text prompt.

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description for the edit
`model`	string	Yes	`fast` or `pro`
`aspect_ratio`	string	Yes	Same options as `generate_image`, plus `auto`
`reference_image_urls`	string[]	Yes	Array of reference image URLs (at least 1)
`quantity`	integer	No	Number of images (1--8, default 1)
`resolution`	string	No	`1k`, `2k`, or `4k` (default `1k`)

Example response:

JSON

{
  "generation_id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "type": "image-edit",
  "status": "processing",
  "quantity": 2,
  "credits_used": 4
}

generate_product_shots

Generate styled product photography from an existing product.

Parameter	Type	Required	Description
`product_id`	string	Yes	UUID of the product
`style_id`	string	Yes	Style preset ID
`model`	string	Yes	`fast` or `pro`
`aspect_ratio`	string	Yes	Same options as `generate_image`
`quantity`	integer	No	Number of images (1--8, default 1)
`resolution`	string	No	`1k`, `2k`, or `4k` (default `1k`)
`additional_prompt`	string	No	Extra instructions for the generation

Example response:

JSON

{
  "generation_id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "type": "product-shots",
  "status": "processing",
  "quantity": 4,
  "credits_used": 8
}

Voiceovers

list_voices

List available voices for voiceover generation. Use the returned voice id when calling generate_voiceover.

Parameter	Type	Required	Description
`gender`	string	No	`male`, `female`, or `other`
`age_group`	string	No	`kid`, `young_adult`, `adult`, or `senior`
`accent`	string	No	`french`, `american`, `british`, `danish`, `swedish`, `german`, `norwegian`, `spanish`, or `neutral`
`style`	string	No	`professional`, `casual`, `energetic`, `whisper`, or `speaker`
`limit`	integer	No	Items per page (1--100, default 20)
`offset`	integer	No	Items to skip (default 0)

Example response:

JSON

{
  "data": [
    {
      "id": "voice_abc123",
      "name": "Sarah",
      "gender": "female",
      "age_group": "adult",
      "accent": "american",
      "style": "professional",
      "preview_audio_url": "https://cdn.adsumo.ai/voices/sarah-preview.mp3"
    }
  ],
  "pagination": { "total": 45, "limit": 20, "offset": 0 }
}

generate_voiceover

Generate a voiceover from text using ElevenLabs. Returns synchronously with the voiceover ID and audio URL. Use before generate_talking_avatar.

Parameter	Type	Required	Description
`text`	string	Yes	The text to speak
`voice_id`	string	Yes	Voice ID from `list_voices`
`model`	string	No	ElevenLabs model (`eleven_multilingual_v2` or `eleven_v3`)
`voice_settings.speed`	number	No	Speech speed
`voice_settings.stability`	number	No	Voice stability
`voice_settings.similarity`	number	No	Voice similarity boost
`voice_settings.style_exaggeration`	number	No	Style exaggeration
`voice_settings.language`	string	No	Language code

Example response:

JSON

{
  "id": "c9d0e1f2-a3b4-5678-cdef-789012345678",
  "status": "completed",
  "duration": 4.5,
  "audio_url": "https://cdn.adsumo.ai/voiceovers/..."
}

speech_to_speech

Convert audio to a different voice (speech-to-speech). Provide an audio URL and a target voice ID.

Parameter	Type	Required	Description
`audio_url`	string	Yes	URL of the source audio
`voice_id`	string	Yes	Target voice ID from `list_voices`
`duration`	number	No	Audio duration in seconds
`voice_settings.speed`	number	No	Speech speed
`voice_settings.stability`	number	No	Voice stability
`voice_settings.similarity`	number	No	Voice similarity boost
`voice_settings.style_exaggeration`	number	No	Style exaggeration
`voice_settings.language`	string	No	Language code

Example response:

JSON

{
  "id": "d0e1f2a3-b4c5-6789-defa-890123456789",
  "status": "completed",
  "duration": 6.2,
  "audio_url": "https://cdn.adsumo.ai/voiceovers/..."
}

Ad Library

scrape_ad_library

Start scraping a brand's ads from the Meta Ad Library. Provide a Meta Ad Library URL. Costs credits.

Parameter	Type	Required	Description
`url`	string	Yes	Meta Ad Library URL for the brand

Example response:

JSON

{
  "job_id": "e1f2a3b4-c5d6-7890-efab-901234567890",
  "status": "processing",
  "brand_id": null
}

list_brands

Browse all brands scraped from the Meta Ad Library. Filter by name or category.

Parameter	Type	Required	Description
`name`	string	No	Filter by brand name (case-insensitive partial match)
`category`	string	No	Filter by page category (case-insensitive partial match)
`limit`	integer	No	Items per page (1--100, default 20)
`offset`	integer	No	Items to skip (default 0)

Example response:

JSON

{
  "data": [
    {
      "id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
      "name": "Nike",
      "page_url": "https://www.facebook.com/nike",
      "page_categories": "Clothing Brand",
      "page_like_count": 35000000,
      "created_at": "2026-03-15T10:00:00Z"
    }
  ],
  "pagination": { "total": 120, "limit": 20, "offset": 0 }
}

list_brand_ads

List ads for a specific brand from the Ad Library.

Parameter	Type	Required	Description
`brand_id`	string	Yes	UUID of the brand
`limit`	integer	No	Items per page (1--100, default 20)
`offset`	integer	No	Items to skip (default 0)

Example response:

JSON

{
  "data": [
    {
      "id": "a3b4c5d6-e7f8-9012-abcd-123456789012",
      "ad_archive_id": "123456789",
      "brand_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
      "is_active": true,
      "start_date": "2026-03-01",
      "body_text": "Just Do It.",
      "display_format": "video",
      "publisher_platforms": ["facebook", "instagram"]
    }
  ],
  "pagination": { "total": 85, "limit": 20, "offset": 0 }
}

get_ad

Get full details of a single ad from the Ad Library.

Parameter	Type	Required	Description
`ad_id`	string	Yes	UUID of the ad

Example response:

JSON

{
  "id": "a3b4c5d6-e7f8-9012-abcd-123456789012",
  "ad_archive_id": "123456789",
  "brand_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
  "is_active": true,
  "start_date": "2026-03-01",
  "body_text": "Just Do It.",
  "title": "Nike Spring Collection",
  "cta_text": "Shop Now",
  "cta_type": "SHOP_NOW",
  "link_url": "https://nike.com/spring",
  "display_format": "video",
  "publisher_platforms": ["facebook", "instagram"],
  "media": [
    {
      "type": "video",
      "r2_url": "https://cdn.adsumo.ai/ads/..."
    }
  ]
}

Resources

list_avatars

List available platform avatars for video generation.

Parameter	Type	Required	Description
`limit`	integer	No	Items per page (1--100, default 20)
`offset`	integer	No	Items to skip (default 0)

Example response:

JSON

{
  "data": [
    {
      "id": "avatar_001",
      "name": "Emma",
      "thumbnail_url": "https://cdn.adsumo.ai/avatars/emma.jpg",
      "gender": "female",
      "age_group": "adult",
      "avatar_type": "realistic"
    }
  ],
  "pagination": { "total": 30, "limit": 20, "offset": 0 }
}

list_custom_avatars

List your team's custom avatars.

Parameter	Type	Required	Description
`limit`	integer	No	Items per page (1--100, default 20)
`offset`	integer	No	Items to skip (default 0)

Example response:

JSON

{
  "data": [
    {
      "id": "b4c5d6e7-f8a9-0123-bcde-234567890123",
      "name": "Brand Spokesperson",
      "description": "Company spokesperson photo",
      "thumbnail_url": "https://cdn.adsumo.ai/custom-avatars/...",
      "created_at": "2026-03-10T08:00:00Z"
    }
  ],
  "pagination": { "total": 3, "limit": 20, "offset": 0 }
}

create_custom_avatar

Create a custom avatar from a photo URL.

Parameter	Type	Required	Description
`name`	string	Yes	Avatar name (1--50 characters)
`image_url`	string	Yes	URL of the face photo
`description`	string	No	Optional description

Example response:

JSON

{
  "id": "c5d6e7f8-a9b0-1234-cdef-345678901234",
  "name": "Brand Spokesperson",
  "status": "completed"
}

list_products

List your team's products.

Parameter	Type	Required	Description
`limit`	integer	No	Items per page (1--100, default 20)
`offset`	integer	No	Items to skip (default 0)

Example response:

JSON

{
  "data": [
    {
      "id": "d6e7f8a9-b0c1-2345-defa-456789012345",
      "name": "Premium Coffee Mug",
      "description": "Ceramic mug with gold trim",
      "category": "Kitchenware",
      "image_url": "https://cdn.adsumo.ai/products/...",
      "price": 29.99,
      "currency": "USD"
    }
  ],
  "pagination": { "total": 12, "limit": 20, "offset": 0 }
}

create_product

Create a new product in your team's catalog.

Parameter	Type	Required	Description
`name`	string	Yes	Product name
`description`	string	Yes	Product description
`category`	string	Yes	Product category
`image_url`	string	Yes	URL of the product image
`price`	number	No	Product price
`currency`	string	No	Currency code (default `USD` if price is set)
`link`	string	No	Product page URL

Example response:

JSON

{
  "id": "e7f8a9b0-c1d2-3456-efab-567890123456",
  "name": "Premium Coffee Mug",
  "status": "completed"
}

get_generation

Poll the status of an async generation (video or image). Use after starting a generation to check if it has completed.

Parameter	Type	Required	Description
`generation_id`	string	Yes	UUID of the generation

Example response (completed AI video):

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "ai-video",
  "status": "completed",
  "result_url": "https://cdn.adsumo.ai/videos/...",
  "error_message": null,
  "created_at": "2026-03-15T12:00:00Z",
  "updated_at": "2026-03-15T12:02:30Z",
  "details": {
    "prompt": "Product showcase with dynamic lighting",
    "model": "sora-2",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}

Example response (image batch):

JSON

{
  "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "type": "image-batch",
  "status": "completed",
  "images": [
    {
      "id": "img-001",
      "status": "completed",
      "result_url": "https://cdn.adsumo.ai/images/...",
      "image_index": 0
    }
  ],
  "credits_used": 4,
  "details": {
    "prompt": "Coffee mug on minimalist desk",
    "mode": "text-to-image",
    "model": "pro",
    "quantity": 4
  }
}

get_credits

Check your team's remaining credits.

No parameters required.

Example response:

JSON

{
  "credits_used": 145,
  "credits_limit": 300,
  "credits_remaining": 155
}