Overview

Generate brand-aligned image and video ads from a single asynchronous API call. Submit a job, get a job_id back immediately, then poll GET /jobs/{job_id} or receive a webhook when the finished creative is ready. Both APIs share the same authentication, job-status endpoint, and credit balance.

Authentication

Every request to the Omneky API — both image and video — is authenticated with an X-API-Key header. API keys are generated from the Omneky Admin Dashboard and are subject to per-key rate limits.

X-API-Key: sk-omn-api01-<your-api-key>

Billing & credits

Omneky runs on a single credit balance shared across the platform and the API. Credits are spent when you generate or edit creative, and when you pull AI performance insights — connecting ad accounts, reporting, and auto-splicing are free. Here's exactly what each action costs.

Image ad generation & editing

Video ad generation & editing

AI insights & launching

Quickstart guide

Submit a job, then poll until it reaches SUCCESS or FAILED. A minimal request only needs brand and product context.

curl -X POST https://api.omneky.com/create_image_ad_async \
  -H "X-API-Key: sk-omn-api01-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_data": {
      "brand_url": "https://yoursite.com",
      "brand_name": "Acme Co"
    },
    "product_metadata": {
      "product_name": "Cloud Runners",
      "product_description": "Lightweight running shoes for daily training"
    }
  }'
# → { "job_id": "a1b2c3d4-5678-90ab-cdef", "type": "image_ad" }

# Poll until SUCCESS or FAILED
curl https://api.omneky.com/jobs/a1b2c3d4-5678-90ab-cdef \
  -H "X-API-Key: sk-omn-api01-<your-key>"

Rate limits

Rate limits are enforced per API key using a fixed one-minute window. When exceeded, the server responds 429 Too Many Requests with a Retry-After header indicating how many seconds until the window resets.

Creates an asynchronous image generation job. The API immediately returns a job_id while generation continues in the background. Typical completion time is 2–5 minutes.

Request body

{
  "brand_data": {
    "brand_url": "https://yoursite.com",
    "brand_name": "Acme Co",
    "brand_images": [
      { "image_url": "https://cdn.example.com/logo.png", "labels": ["logo"] }
    ],
    "fonts": ["https://example.com/fonts/Poppins-Medium.ttf"],
    "color_swatches": [
      { "hex": "#FF5733", "label": "headline" }
    ]
  },
  "product_metadata": {
    "product_url": "https://yoursite.com/products/cloud-runner",
    "product_name": "Cloud Runners",
    "product_description": "Lightweight running shoes for daily training",
    "product_images": [
      { "image_url": "https://cdn.example.com/shoe.jpg", "labels": ["top view"] }
    ]
  },
  "ad_copies": [
    { "copy_type": "headline",    "copy_text": "Run Farther, Feel Lighter" },
    { "copy_type": "subheadline", "copy_text": "Built for everyday athletes" },
    { "copy_type": "cta",         "copy_text": "Shop Now" },
    { "copy_type": "offer",       "copy_text": "20% Off This Week", "price": "$79.99" }
  ],
  "generation_metadata": {
    "aspect_ratios": "1:1",
    "user_direction": "Outdoor trail scene with golden hour lighting",
    "language": "en-us",
    "no_text": false,
    "resolution": "1K",
    "reference_layouts": "https://cdn.example.com/reference.jpg"
  },
  "callback_url": "https://yourserver.com/webhooks/omneky"
}

brand_data

product_metadata (optional)

ad_copies (optional)

generation_metadata

Response — 202 Accepted

{
  "job_id": "a1b2c3d4-5678-90ab-cdef",
  "type": "image_ad"
}

Returns the current status of a generation job. This endpoint is shared with video ad jobs — the type field indicates whether the job is "image_ad" or "video_ad". Jobs are private to the API key that created them.

Response — 200 OK

{
  "job_id": "a1b2c3d4-5678-90ab-cdef",
  "type": "image_ad",
  "status": "SUCCESS",
  "response": { "...": "generated ad" },
  "error": null
}

Job status values

Background pipeline

Each submitted job passes through the following pipeline:

Step 1 — Brand onboarding (optional)

If brand_data.brand_url or product_metadata.product_url is supplied, Omneky extracts brand colors, fonts, logos, headlines, CTAs, and product information. Failures during onboarding do not fail the job.

Step 2 — Ad concept generation (optional)

If generation_metadata.user_direction is not supplied, Omneky generates an AI creative concept that becomes the creative brief. If user_direction is supplied, this step is skipped.

Step 3 — Image generation

The final payload — brand identity, product information, creative concept, and copy — is passed to Omneky's image generation model to produce the final advertisement.

Webhooks

Instead of polling, provide a callback_url. When processing finishes, Omneky sends a POST request containing the same payload returned by the job-status endpoint.

{
  "job_id": "a1b2c3d4-5678-90ab-cdef",
  "type": "image_ad",
  "status": "SUCCESS",
  "response": { "...": "generated ad" },
  "error": null
}

{
  "job_id": "a1b2c3d4-5678-90ab-cdef",
  "type": "image_ad",
  "status": "FAILED",
  "response": null,
  "error": "Downstream generation model returned an error"
}

Error reference

Recommended polling strategy

1. Submit the generation request.
2. Store the returned job_id.
3. If a webhook was configured, wait for the callback.
4. Otherwise: wait 30 seconds before the first poll, then poll every 60 seconds.
5. Treat the request as timed out if it has not completed within 30 minutes.

Quickstart guide

Submit a job, then poll until it succeeds or fails. A minimal request needs brand, product, and generation metadata.

curl -X POST https://api.omneky.com/create_video_ad_async \
  -H "X-API-Key: sk-omn-api01-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_metadata": {
      "brand_url": "https://yoursite.com",
      "brand_name": "Acme Co",
      "brand_images": null
    },
    "product_metadata": {
      "product_name": "Cloud Runners",
      "product_description": "Lightweight running shoes for daily training",
      "product_images": [
        { "image_url": "https://cdn.example.com/shoe.jpg" }
      ]
    },
    "generation_metadata": {
      "aspect_ratio": "9:16",
      "target_duration": 12,
      "locale": "en-US",
      "user_prompt": "Energetic morning run, urban trail setting"
    }
  }'
# → { "job_id": "a1b2c3d4-...", "type": "video_ad" }

# Poll until SUCCESS or FAILED
curl https://api.omneky.com/jobs/a1b2c3d4-... \
  -H "X-API-Key: sk-omn-api01-<your-key>"

Rate limits

Rate limits are enforced per API key using a fixed per-minute window. When the limit is hit, the server responds 429 with a Retry-After: N header indicating how many seconds until the window resets.

Submits a video generation job. Returns immediately with 202 Accepted and a job_id; generation runs in the background and typically completes in 3–7 minutes.

Request body

{
  "brand_metadata": {
    "brand_url": "https://www.peets.com",
    "brand_name": "Peet's Coffee",
    "brand_images": [
      { "image_url": "https://cdn.example.com/logo.png", "description": "Brand logo", "labels": ["logo"] },
      { "image_url": "https://cdn.example.com/lifestyle.jpg", "description": "Morning coffee ritual", "labels": ["lifestyle"] }
    ],
    "fonts": ["Montserrat", "Roboto"],
    "color_swatches": [
      { "hex": "#1A1A1A", "label": "Primary Black" },
      { "hex": "#C4A35A", "label": "Gold Accent" }
    ]
  },
  "product_metadata": {
    "product_url": "https://www.peets.com/products/big-bang",
    "product_name": "Peet's Big Bang Coffee",
    "product_description": "Bold whole bean coffee with a smooth finish and rich aroma.",
    "product_images": [
      { "image_url": "https://cdn.example.com/product-front.png", "description": "Product front view", "labels": ["top view"] },
      { "image_url": "https://cdn.example.com/product-closeup.png", "description": "Bean close-up", "labels": ["detail"] }
    ]
  },
  "ad_copies": [
    { "copy_type": "headline",    "copy_text": "Start Your Morning Bold" },
    { "copy_type": "subheadline", "copy_text": "Whole bean coffee, rich aroma" },
    { "copy_type": "cta",         "copy_text": "Shop Now" }
  ],
  "generation_metadata": {
    "aspect_ratio": "9:16",
    "target_duration": 12,
    "locale": "en-US",
    "user_prompt": "Lean into the morning ritual angle",
    "generate_sound": false
  },
  "callback_url": "https://yourserver.com/webhooks/omneky"
}

Field reference

Aspect ratio → orientation

Response — 202 Accepted

{
  "job_id": "a1b2c3d4-5678-...",
  "type": "video_ad"
}

Poll this endpoint to check generation progress. It is shared with image ad jobs — the type field indicates whether the job is "video_ad" or "image_ad". For long-running jobs, prefer setting a callback_url instead of busy-polling.

Response — 200 OK

{
  "job_id": "a1b2c3d4-5678-...",
  "type": "video_ad",
  "status": "SUCCESS",
  "response": { "...video generation result..." },
  "error": null
}

Job status values

Background pipeline

When a job is submitted, the following steps run in the background:

Step 1 — Brand onboarding (optional, non-fatal)

If brand_metadata.brand_url or product_metadata.product_url is provided, Omneky scrapes it to extract colors, fonts, headlines, CTAs, and product info. Explicit fonts and color_swatches override scraped values. Failure here is non-fatal — generation continues with what was supplied directly.

Step 2 — Narrative & script (mandatory)

Omneky's AI generates a narrative, voiceover script, and scene segments based on product info, images, target_duration, locale, and user_prompt.

Step 3 — Video generation (mandatory)

The assembled payload (brand identity + narrative + segments + copy) is passed to the multi-scene video generation model to produce the final product video.

Webhooks

Set callback_url in your request to receive a POST notification when the job finishes (success or failure) — the recommended alternative to polling. The payload is identical to the GET /jobs/{job_id} response.

{
  "job_id": "a1b2c3d4-5678-...",
  "type": "video_ad",
  "status": "SUCCESS",
  "response": { "...video generation result..." },
  "error": null
}

{
  "job_id": "a1b2c3d4-5678-...",
  "type": "video_ad",
  "status": "FAILED",
  "response": null,
  "error": "No narratives found"
}

Error reference

Recommended polling strategy

1. Submit the job and store the job_id.
2. If you provided a callback_url, wait for the webhook.
3. If polling: wait at least 60 seconds before the first poll, then poll every 90 seconds.
4. Treat a job as timed out if it has not reached SUCCESS or FAILED after 45 minutes.