Ads

Paste the product link. We read the page itself and stage an ad that sells it, in every placement format.

The product photo→The ad, read out of the product page

Give the product page and a style. The server scrapes the page for the offer and the product, then composes the layout, the copy rules and the fidelity clauses. Your prompt only describes the look.

Billed per image. $0.20, which covers reading the page as well as the render. Live rate from GET /v3/pricing.

A complete call

A 4:5 ad read straight from a product page, fronted by one person.

curl -X POST "https://api.neurall.io/v3/files/upload" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -F "files=@person.jpg" \
  -F "files=@headphones.jpg"

{
  "files": [
    {
      "id": "f_9c21e0b4",
      "originalName": "person.jpg",
      "size": 812340
    },
    {
      "id": "f_2ab7710d",
      "originalName": "headphones.jpg",
      "size": 402118
    }
  ]
}

curl -X POST "https://api.neurall.io/v3/generations" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "image/ad",
    "args": {
      "productUrl": "https://example.com/products/aurora-3-headphones",
      "prompt": "Bold retail energy: saturated gradient background, oversized headline space, one high-contrast call to action, product hero-lit.",
      "composition": "person-product",
      "images": [
        "f_9c21e0b4",
        "f_2ab7710d"
      ],
      "expressions": [
        "happy"
      ],
      "aspectRatio": "4:5"
    }
  }'

{
  "generation": {
    "id": "a1f5…",
    "feature": "image/ad",
    "kind": "image",
    "status": "pending"
  }
}

# repeat every 2s or so until status is done, error or timeout
curl "https://api.neurall.io/v3/generations/9f2c1d84-6a3b-4f21-9c77-2f0a1b8e5d43" \
  -H "Authorization: nl-YOUR_API_KEY"

{
  "generation": {
    "status": "done",
    "output": {
      "image": "https://cdn.neurall.io/…/image.png",
      "mime": "image/png"
    }
  }
}

Arguments

productUrlstring

The product or promo page. We fetch it and read the offer, the product and its details. Send this OR productDescription, never both.

• A well-formed http(s) URL with a dotted hostname, at most 2000 characters.

productDescriptionstring

What is being sold, when there is no page to read. The alternative to productUrl.

• At most 2000 characters.

promptstringrequired

The creative STYLE only: palette, layout energy, treatment. Every legibility and fidelity clause is appended server-side.

• At most 2000 characters.

composition'person' | 'person-product' | 'ad-only'defaults to 'person'

What is in the frame: someone holding the pitch, someone with the product, or the ad alone with no people.

imagesarray

The references, in the order the composition implies. Each entry is a plain file id from POST /v3/files/upload.

• PNG, JPEG, WebP, GIF, HEIC or AVIF, up to 30 MB and 30 megapixels per file, 10 files per upload request.
• An uploaded file is deleted 24 hours after it lands, so upload again for a later render rather than caching an id.
• ad-only takes none: the page copy carries the ad.

How the prompt refers to these

args.images[0]The person

Call them "the person" if the prompt mentions them. Never describe their face: it is preserved from the photo.

args.images[1]The product

On person-product this is the product. Refer to it as "the product" and the render maps that word to this image.

expressionsstring[]

One expression per person in the composition.

brandobject

Brand kit values, raw: background, text and accent are hex colors, all three required when brand is sent; name and voice (a short tone description) are optional strings; logo is an optional file id from POST /v3/files/upload (upload the logo file first); do not put it in images or count it in the composition, the server adds it after the reference photos and places it small in one corner.

aspectRatio'4:5' | '1:1' | '16:9' | '9:16'defaults to '4:5'

The placement it ships in. 4:5 is the default: the tallest unit the feeds allow, so it takes the most screen on a phone.

The product is reproduced faithfully from its photo. Describing it in words competes with the image and is how a render ends up selling the wrong thing.

Output

Once status is done, the generation carries an output object with these fields. On any other status, output is absent.

imagestring

The finished ad creative, as a URL.

• A signed URL that expires 24 hours after the request (expiresAt on the generation). Download the file rather than hotlinking it.

mimestring

The image's MIME type, e.g. image/png.

Limits and failure

Product source

Exactly one of productUrl or productDescription.

Images

As many as the composition implies, 30 MB and 30 megapixels each, deleted 24 hours after upload.

Likeness

A real person in the frame requires their permission; the Terms of Use cover it, there is nothing to send.

Render time

A generation that has not finished in 15 minutes is marked timeout and refunded.

Concurrency

Your plan caps how many generations run at once. Over it the API answers 429 with a Retry-After header.

Output lifetime

API-created outputs expire 24 hours after the request. Download the file rather than hotlinking it.

Deletion

DELETE /v3/generations/{id} removes the generation and its rendered assets immediately, rather than waiting for the 24 hour expiry. It does not refund anything and cannot cancel a render already in flight.

Failure

A failed or timed-out generation is refunded automatically.

Worth knowing

• Reading the page happens server-side, through a crawl API, and is part of the price.
• The same call at four ratios gives you the whole placement set; each is billed separately.