---
title: "Marketing banner (picture or 15-second video) from a brief"
method: POST
path: "/v1/banner"
tags: ["Banners"]
---

# Marketing banner (picture or 15-second video) from a brief

`POST /v1/banner`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/banner`
- Auth: HTTP bearer

One call with a short brief returns a finished marketing banner for a business, square 1080×1080: a picture (JPEG) in one of four styles, or a 15-second video (MP4 with music, plus a poster) in one of four animated styles. Asynchronous: the call answers 202; poll GET /v1/executions/{id} for `output.url`. Styles — pictures: `natural` (a person beside a big curved white panel, a handwritten line, a huge price, a gift ribbon, three benefits on a brush stroke), `premium` (a tall photo beside a black-and-gold panel, a framed second photo, gold icons, the price), `clean` (a white arch with the headline over a bright photo, a blue price box with a gift, a round stamp, two benefit pills), `sporty` (a cut-out person over slanted yellow-and-white bars on navy, a huge 'free' or price, a button); videos: `motion-red` (graphite and red: a full-screen hook, a split screen with the work and a counting price, numbered steps, a call to action), `motion-gold` (black and gold, round badges — food, evening), `motion-sea` (turquoise and coral, slanted bars — sea, sport, kids), `motion-cream` (cream and bronze, slow — spa, beauty, gifts). How it works: the planner writes the style's own fields from your brief (a local hook, the headline, the price, the gift, three benefits with icons, the button…) — prices, discounts, gifts, numbers and places ONLY from your brief, never invented; your own `copy` fields are kept as you wrote them. Media: your photos (`images`) and clips (`videos`) first; without them a picture style gets a photo generated for it (Gemini 3 Pro Image, composed for the style: the person where the panel leaves room) and an animated style gets free stock clips picked and checked for the topic (no stock person, no brand). Your `business.logo_url` sits in a badge of its own background colour; without one the business's name is set in its place. The main photo's subject is found and, in `natural` and `sporty`, cut out and laid over the panel. Text is set by our render engine — real Hebrew right to left, real fonts, prices and numbers read correctly; long words shrink to fit, never overflow. The videos carry a music bed of the style's mood from our library (or `music: "none"`, or your own link) and soft transition sounds. Every banner also comes as an editable file, `editable_url` (PPTX: the photo, the logo and the design as separate layers, every text a real text box in its font, size and colour) — the customer drags it into Canva (or opens it in PowerPoint, Google Slides, Keynote) and changes a word, the price, the photo or the logo themselves; an animated banner's file is the moment of its offer, the footage's frame as the photo. Every banner comes with a post caption and at most 5 hashtags, and its `plan`: change a word, the price, a picture or the colours and send it to POST /v1/banner/render — no model runs again, only the render is charged. The files are kept 24 hours. The price is the real cost of what ran (the planner, each generated picture, the stock check, the render) times the standard markup; the estimate is the worst case and is what is reserved.

**Billing:** Real cost of the run × the standard markup: the planner, each generated picture or the stock check, and the render (a picture, or a 15-second video) · **Rate limit:** 6/min · **Asynchronous**

## Headers

- `Idempotency-Key` string
- `X-Tag` string
- `x-wait-ms` integer

## Request body

- object
  - `copy` object: Your own words for some fields (the rest are written for you); with every required field of the style the planner is skipped
    - `cta` string
    - `tag` string
    - `fine` string
    - `gift` string
    - `hook` string
    - `list` string[]
    - `tag2` string
    - `badge` object
      - `big` string, required
      - `sub` string
      - `top` string
      - `bottom` string
    - `chips` string[]
    - `hook2` string
    - `price` object
      - `amount` string, required
      - `prefix` string
      - `suffix` string
      - `currency` string
    - `script` string
    - `details` string
    - `end_big` string
    - `end_sub` string
    - `big_word` string
    - `end_icon` 'users' | 'award' | 'circle-parking' | 'coffee' | 'flame' | 'clock' | 'leaf' | 'shield-check' | 'shield' | 'droplets' | 'sparkles' | 'truck' | 'fish' | 'salad' | 'soup' | 'life-buoy' | 'map-pin' | 'sun' | 'star' | 'heart' | 'house' | 'hand-heart' | 'gift' | 'phone' | 'calendar-check' | 'scissors' | 'car-front' | 'baby' | 'graduation-cap' | 'cpu' | 'rocket' | 'waves' | 'wind' | 'thermometer-snowflake' | 'badge-check' | 'timer' | 'smile' | 'flower-2' | 'wine' | 'bath' | 'check' | 'message-circle' | 'dumbbell' | 'utensils' | 'pizza' | 'shopping-bag' | 'stethoscope' | 'paw-print' | 'book-open' | 'music' | 'camera' | 'wrench' | 'zap' | 'wifi' | 'percent' | 'tag' | 'headphones' | 'shirt' | 'bike' | 'plane'
    - `end_lead` string
    - `features` object[]
      - `icon` 'users' | 'award' | 'circle-parking' | 'coffee' | 'flame' | 'clock' | 'leaf' | 'shield-check' | 'shield' | 'droplets' | 'sparkles' | 'truck' | 'fish' | 'salad' | 'soup' | 'life-buoy' | 'map-pin' | 'sun' | 'star' | 'heart' | 'house' | 'hand-heart' | 'gift' | 'phone' | 'calendar-check' | 'scissors' | 'car-front' | 'baby' | 'graduation-cap' | 'cpu' | 'rocket' | 'waves' | 'wind' | 'thermometer-snowflake' | 'badge-check' | 'timer' | 'smile' | 'flower-2' | 'wine' | 'bath' | 'check' | 'message-circle' | 'dumbbell' | 'utensils' | 'pizza' | 'shopping-bag' | 'stethoscope' | 'paw-print' | 'book-open' | 'music' | 'camera' | 'wrench' | 'zap' | 'wifi' | 'percent' | 'tag' | 'headphones' | 'shirt' | 'bike' | 'plane', required
      - `label` string, required
    - `headline` string
    - `includes` string
    - `location` string
    - `headline2` string
    - `script_latin` string
  - `plan` object: A plan returned by an earlier call (possibly edited): nothing is planned or generated, only rendered
    - `copy` object, required
      - `cta` string
      - `tag` string
      - `fine` string
      - `gift` string
      - `hook` string
      - `list` string[]
      - `tag2` string
      - `badge` object
        - `big` string, required
        - `sub` string
        - `top` string
        - `bottom` string
      - `chips` string[]
      - `hook2` string
      - `price` object
        - `amount` string, required
        - `prefix` string
        - `suffix` string
        - `currency` string
      - `script` string
      - `details` string
      - `end_big` string
      - `end_sub` string
      - `big_word` string
      - `end_icon` 'users' | 'award' | 'circle-parking' | 'coffee' | 'flame' | 'clock' | 'leaf' | 'shield-check' | 'shield' | 'droplets' | 'sparkles' | 'truck' | 'fish' | 'salad' | 'soup' | 'life-buoy' | 'map-pin' | 'sun' | 'star' | 'heart' | 'house' | 'hand-heart' | 'gift' | 'phone' | 'calendar-check' | 'scissors' | 'car-front' | 'baby' | 'graduation-cap' | 'cpu' | 'rocket' | 'waves' | 'wind' | 'thermometer-snowflake' | 'badge-check' | 'timer' | 'smile' | 'flower-2' | 'wine' | 'bath' | 'check' | 'message-circle' | 'dumbbell' | 'utensils' | 'pizza' | 'shopping-bag' | 'stethoscope' | 'paw-print' | 'book-open' | 'music' | 'camera' | 'wrench' | 'zap' | 'wifi' | 'percent' | 'tag' | 'headphones' | 'shirt' | 'bike' | 'plane'
      - `end_lead` string
      - `features` object[]
        - `icon` 'users' | 'award' | 'circle-parking' | 'coffee' | 'flame' | 'clock' | 'leaf' | 'shield-check' | 'shield' | 'droplets' | 'sparkles' | 'truck' | 'fish' | 'salad' | 'soup' | 'life-buoy' | 'map-pin' | 'sun' | 'star' | 'heart' | 'house' | 'hand-heart' | 'gift' | 'phone' | 'calendar-check' | 'scissors' | 'car-front' | 'baby' | 'graduation-cap' | 'cpu' | 'rocket' | 'waves' | 'wind' | 'thermometer-snowflake' | 'badge-check' | 'timer' | 'smile' | 'flower-2' | 'wine' | 'bath' | 'check' | 'message-circle' | 'dumbbell' | 'utensils' | 'pizza' | 'shopping-bag' | 'stethoscope' | 'paw-print' | 'book-open' | 'music' | 'camera' | 'wrench' | 'zap' | 'wifi' | 'percent' | 'tag' | 'headphones' | 'shirt' | 'bike' | 'plane', required
        - `label` string, required
      - `headline` string
      - `includes` string
      - `location` string
      - `headline2` string
      - `script_latin` string
    - `brand` object
      - `name` string
      - `accent` string
      - `primary` string
      - `logo_url` string, uri
    - `clips` object[]
      - `url` string, uri, required
      - `start` number
      - `focus_x` number
      - `focus_y` number
    - `style` 'natural' | 'premium' | 'clean' | 'sporty' | 'motion-red' | 'motion-gold' | 'motion-sea' | 'motion-cream', required
    - `cutout` boolean
    - `caption` string
    - `version` 1
    - `hashtags` string[]
    - `language` 'he' | 'en'
    - `decor_url` string, uri
    - `music_url` string, uri
    - `photo_url` string, uri
    - `photo2_url` string, uri
    - `sticker_cut` boolean
    - `sticker_url` string, uri
  - `brief` string: The business and the offer in your words: what you sell, the price, the gift, the place, who it is for. Prices, discounts, gifts and places are taken ONLY from here — nothing is invented
  - `media` 'auto' | 'own' | 'ai' | 'stock': auto = your files when you send them, else: a generated photo (pictures) or free stock clips checked for the topic (videos) · ai = generate the photos (Gemini 3 Pro Image) · stock = free stock clips (videos only) · own = only your files
  - `music` union: Videos: auto = a track of the style's mood from our library · none = silence · or a link to your own music
    - 'auto' | 'none'
    - string, uri
  - `style` 'natural' | 'premium' | 'clean' | 'sporty' | 'motion-red' | 'motion-gold' | 'motion-sea' | 'motion-cream', required: natural · premium · clean · sporty (pictures, 1080×1080 JPEG) — motion-red · motion-gold · motion-sea · motion-cream (15-second videos, 1080×1080 MP4)
  - `images` string[]: Your own photos (JPEG / PNG / WebP): the first is the main picture, the second the framed one (premium). Without them: `media`
  - `videos` union[]: Animated styles: your own clips (MP4 / MOV), in order — each fills one window of the style (fewer clips are reused further in). A link, or { url, start, focus_x, focus_y }
    - union
      - string, uri
      - object
        - `url` string, uri, required
        - `start` number: where to start reading the clip, seconds
        - `focus_x` number: which part stays when the clip is cropped into its window: 0 left … 1 right
        - `focus_y` number
  - `brand_id` string: A brand of yours (GET /v1/brands): its name, logo and colours fill what `business` leaves out — `default` = your default brand
  - `business` object
    - `name` string: The business's name — printed in the logo's place when there is no logo
    - `accent` string: Your accent colour, #RRGGBB
    - `primary` string: Your main colour, #RRGGBB — replaces the style's
    - `logo_url` string, uri: Your logo (PNG with transparency is best; JPEG works — it sits in a round badge of its own background colour)
  - `language` 'he' | 'en'
  - `photo_direction` string: A line on what the generated photo should show (who, where, the mood)

## Response `200`

Completed (or 202 while processing)

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `202`: Processing — poll GET /v1/executions/{id}
- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)