Create Image Ad API

Generate a brand-aligned, on-product image ad from a single API call. Send Omneky your brand assets, product imagery, and ad copy — the agent reads your positioning, composition, and color, then returns a ready-to-launch creative.

Authentication

Every request to the Omneky API is authenticated with an API key issued from your workspace settings. Pass it as a bearer token on every request, server-side only.

Authorization: Bearer YOUR_API_KEY

Quickstart guide

Prerequisites

Before you begin, make sure you have:

• An Omneky account with API access enabled
• Your API key (see Authentication above)
• Publicly accessible URLs for any brand or product images you reference

Building a request means assembling four pieces — brand_data, product_metadata, ad_copies, and generation_metadata — then POSTing them to /create_image_ad_async. Generation runs asynchronously: you get a job_id back right away and either poll for the result or receive it at your callback_url. The sections below walk through each piece.

Tells Omneky who the ad is for. Provide a brand URL for Omneky to scrape automatically, or supply brand images, fonts, and colors directly for tighter control.

Describes the product the ad should feature.

The lines of copy Omneky should render onto the creative.

Controls how the creative is generated — format, layout inspiration, and freeform direction.

Because generation runs asynchronously, Omneky notifies you when the ad is ready rather than holding the connection open.

Submission response

A successful call to POST /create_image_ad_async doesn't return the finished ad — it returns immediately with a job to track.

{
  "job_id": "8f1d2a3e-9c44-4b77-9e2a-2f0b6a5d11c0",
  "type": "image_ad"
}

Check job status

Poll this endpoint with the job_id from the submission response to track progress and retrieve the result once it's ready.

{
  "job_id": "8f1d2a3e-9c44-4b77-9e2a-2f0b6a5d11c0",
  "type": "image_ad",
  "status": "SUCCESS",
  "response": {}
}

Example request & response

Putting it all together — a complete request for a skincare brand, the immediate 202 acknowledgement, and a status check once the job finishes.

curl --request POST \
  --url https://api.omneky.com/create_image_ad_async \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "brand_data": {
      "brand_url": "https://www.exampleskincare.com",
      "brand_images": [
        {
          "image_url": "https://cdn.exampleskincare.com/logo.png",
          "description": "Primary brand logo",
          "labels": ["logo"]
        }
      ],
      "fonts": ["Inter", "DM Sans"],
      "color_swatches": [
        { "hexcode": "#322996", "label": "Brand Indigo" },
        { "hexcode": "#D4384F", "label": "Brand Red" }
      ]
    },
    "product_metadata": {
      "product_url": "https://www.exampleskincare.com/products/vitamin-c-serum",
      "product_images": [
        {
          "image_url": "https://cdn.exampleskincare.com/serum-front.jpg",
          "description": "Vitamin C serum, front label",
          "labels": ["front view"]
        }
      ]
    },
    "ad_copies": [
      { "copy_text": "Brighter skin in 14 days", "copy_type": "headline" },
      { "copy_text": "Dermatologist tested, vegan formula", "copy_type": "subheadline" },
      { "copy_text": "Shop Now", "copy_type": "cta" }
    ],
    "generation_metadata": {
      "aspect_ratios": ["1:1", "4:5"],
      "reference_layouts": [],
      "user_direction": "Bright, clean studio lighting with the serum bottle centered."
    },
    "callback_url": "https://www.exampleskincare.com/webhooks/omneky"
  }'

# 202 Accepted — returned immediately
{
  "job_id": "8f1d2a3e-9c44-4b77-9e2a-2f0b6a5d11c0",
  "type": "image_ad"
}

# GET /jobs/8f1d2a3e-9c44-4b77-9e2a-2f0b6a5d11c0 → 200 OK
{
  "job_id": "8f1d2a3e-9c44-4b77-9e2a-2f0b6a5d11c0",
  "type": "image_ad",
  "status": "SUCCESS",
  "response": {}
}

Full parameter reference

Every field accepted by POST /create_image_ad_async, in one place.

Summary