Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fattly-app:fattly-app-ad-studio-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fattly Ad Studio API
version: 1.0.0
summary: UGC video ads, AI images, video and voiceovers from 40+ models.
description: 'REST API of fattly.app — the same engine as the web app, the CLI (`npm i -g fattly`) and the MCP server (`https://fattly.app/api/mcp`).
**Auth:** create a key at fattly.app → Dashboard → API keys and send `Authorization: Bearer gpx_live_...`.
**Billing:** every generation spends credits from the key owner''s account (GET /api/models lists prices). Failed generations are refunded automatically. Keys can have a daily spend limit.
**Async jobs:** video, video ads and other long jobs return an `id` — poll GET /api/video/status?id=... every 5-10 s until `completed` or `failed`.
**Inputs:** image inputs must be URLs returned by POST /api/upload.
**Content policy:** safe-for-work only, adults only, use only faces and voices you have the right to use.
**Ad presets and creator avatars:** preset ids (templateId) and avatars are listed by the MCP tools fattly_list_ad_presets and fattly_create_avatar (MCP server: https://fattly.app/api/mcp).'
contact:
name: Fattly
url: https://fattly.app
email: contact@fattly.app
termsOfService: https://fattly.app/regulamin
servers:
- url: https://fattly.app
security:
- bearerAuth: []
tags:
- name: Ad Studio
description: Turn a product photo into ads.
paths:
/api/ugc/video:
post:
tags:
- Ad Studio
operationId: createAdVideo
summary: UGC video ad (about 150 credits, async)
description: 'Ad Studio VIDEO ad (premium, ~150 credits): a real-looking creator presents your product on camera with a real voice — the full site flow. Returns a job id — poll /api/video/status.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mode:
type: string
enum:
- product
- service
- handsdemo
- unboxing
description: 'product = creator holds your product (needs productImageUrl). service = creator talks to camera, no product in frame. handsdemo = POV hands + product, NO face on screen, voice-over off camera (this is the site mode named: no avatar; needs productImageUrl). unboxing = silent ASMR unboxing, hands only, no speech — `script` is ignored, steer the shot with `prompt` instead.'
script:
type: string
description: 'What the creator SAYS on camera, word for word. Keep it short — a few seconds of speech. Optional: with no script we write one from `prompt` for free. Ignored in unboxing mode (that ad has no speech).'
prompt:
type: string
description: The idea / how the shot should look (room, lighting, what the creator does). Not spoken — it directs the scene. Also the source we write the script from when `script` is empty.
aspectRatio:
type: string
enum:
- '9:16'
- '16:9'
description: 'Video shape: 9:16 vertical (default, TikTok/Reels) or 16:9 landscape.'
productUrl:
type: string
description: Product photo as a fal URL — REQUIRED for product mode. Use POST /api/upload.
actorId:
type: string
description: Avatar you generated with fattly_create_avatar — the SAME creator presents the product.
avatarId:
type: string
description: Creator from the built-in roster (see fattly_list_ad_presets).
avatarUrl:
type: string
description: 'Your own creator photo as a fal URL. Using a photo of a real person requires consent: true.'
templateId:
type: string
description: Ad preset id — must be a non-graphic preset (see fattly_list_ad_presets).
setting:
type: string
description: Scene id from fattly_list_ad_presets.
locale:
type: string
enum:
- en
- pl
- de
- es
- fr
description: Spoken language (default en). EN uses native Kling audio; other languages use Gemini Omni 1.1.
voice:
type: string
description: Voice name for non-EN locales.
unbranded:
type: boolean
description: Keep the product free of invented branding.
consent:
type: boolean
description: REQUIRED (true) when you pass avatarUrl (your own creator photo). Must be true. By setting it you confirm that you have the rights to, and the consent of, every person who is visible or audible in the materials you provide.
required:
- mode
additionalProperties: false
responses:
'200':
description: Job started
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Job id — poll GET /api/video/status?id=... until completed or failed.
cost:
type: integer
description: Credits charged.
required:
- id
'400':
description: Invalid input or blocked content
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing, invalid or revoked API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Not enough credits
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit or daily key spend limit reached
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/ugc:
post:
tags:
- Ad Studio
operationId: createAdImage
summary: Ad image from a product photo (20 credits)
description: 'Ad Studio: turns a product photo into a finished ad (20 credits). graphic = product alone in a styled scene; product = a creator holding it; service = a creator with no product. Pick templateId with fattly_list_ad_presets. Upload the product photo with POST /api/upload first.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mode:
type: string
enum:
- graphic
- product
- service
description: graphic = product only (needs productImageUrl). product = creator + product (needs productImageUrl AND a creator). service = creator only (needs prompt AND a creator).
productUrl:
type: string
description: Product photo as a fal URL — REQUIRED for graphic and product modes. Get one with POST /api/upload.
templateId:
type: string
description: Ad preset id from fattly_list_ad_presets. Must match the mode (graphic presets only in graphic mode, and vice versa).
avatarId:
type: string
description: Creator from the built-in roster (product/service modes). See fattly_list_ad_presets.
avatarUrl:
type: string
description: 'Your own creator photo as a fal URL (alternative to avatarId). Using a photo of a real person requires consent: true.'
actorId:
type: string
description: Id of an avatar you generated earlier on this account („My actors”).
setting:
type: string
description: Scene id from fattly_list_ad_presets (scenes).
prompt:
type: string
description: What the ad is about — REQUIRED for service mode. Any language; it is translated to English server-side.
aspectRatio:
type: string
description: 'Graphic mode only: 1:1, 2:3, 9:16 or 16:9 (default 1:1). Ignored in product/service modes, which are always 9:16.'
unbranded:
type: boolean
description: Keep the product free of invented logos/branding.
consent:
type: boolean
description: REQUIRED (true) when you pass avatarUrl (your own creator photo). Must be true. By setting it you confirm that you have the rights to, and the consent of, every person who is visible or audible in the materials you provide.
required:
- mode
additionalProperties: false
responses:
'200':
description: Finished ad image
content:
application/json:
schema:
type: object
properties:
id:
type: string
url:
type: string
format: uri
required:
- url
'400':
description: Invalid input or blocked content
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing, invalid or revoked API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Not enough credits
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit or daily key spend limit reached
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key gpx_live_... from fattly.app → Dashboard → API keys.
externalDocs:
description: MCP / Claude setup
url: https://fattly.app/claude-mcp