Skip to main content

REST API Guide

This guide explains what the NativeAds REST API does and the recommended path from a brand to finished creatives. For request and response schemas, field types, and every endpoint, use the API Reference. The raw headless.yaml spec is also downloadable for Postman or Insomnia.

What NativeAds does​

NativeAds is a creative-generation platform you drive over HTTP. You manage brands, teach the system each brand’s look and voice (Brand DNA), upload product and reference assets, then generate on-brand product images and videos.

The usual path looks like this:

Brand DNA is what keeps output on-brand. You can generate without it, but results will look generic.

Get an API key​

  1. Sign in at https://app.nativeads.ai.
  2. Open Settings → Account → API Keys.
  3. Click Create, give the key a name (optional expiry), and confirm.
  4. Copy the full token immediately and store it in a secret manager. It is shown once and cannot be retrieved again.

Keys look like nak_production_<keyId>.<secret>.

A key acts as its owning user inside that user’s organization — same permissions, no more. Deleting or regenerating a key takes effect on the next request. Treat it like a password.

Base URL and authentication​

Base URL: https://creative-v1.nativeads.ai/v1

Send the key as a bearer token on every request:

Authorization: Bearer nak_production_<keyId>.<secret>

Quick smoke test — list brands:

curl https://creative-v1.nativeads.ai/v1/brands \
  -H "Authorization: Bearer nak_production_<keyId>.<secret>"

A 200 with a list (even empty) means the key works. Invalid or expired keys return 401. Endpoints outside the developer surface return 403.

End-to-end workflow​

Follow the steps in order. Each step links to the matching operations in the API Reference for exact payloads. Brand DNA, prompt enhancement, image generation, and video generation are asynchronous: the create call returns a resource id immediately, then you poll that resource’s GET endpoint until it finishes.

1. Create a brand​

A brand is the container for everything about one product or company: name, industry, description, tone, and later its DNA, assets, and generations.

Create one with a name (other fields are optional), or list existing brands if you already have them.

API Reference: Create a brand · List brands · Get a brand · Update a brand

2. Upload assets​

Upload product photos, logos, environment images, brand-guideline PDFs, or videos.

Uploading is always three steps:

  1. Get an upload URL (initiate-upload) — send the file’s name, type, size, and dimensions. You get a short-lived upload URL, plus an uploadId and assetId.
  2. Upload the file — send the file to that URL. Do not send your API key here; the link already authorizes the upload and expires quickly.
  3. Confirm the upload (confirm-upload) — tell NativeAds the file is in place. NativeAds then processes it (thumbnails, checks). Poll Get asset until status is complete (or failed) before using the asset in Brand DNA or generation.

Allowed types: JPEG, PNG, GIF, TIFF, MP4, QuickTime, PDF, DOC, DOCX, and the TTF/OTF/WOFF/WOFF2 fonts (max 500 MB). SVG is not accepted — rasterise it first. For a logo, set isLogo: true in the initiate request.

API Reference: Initiate upload · Confirm upload · Cancel upload · Get asset · List brand assets

Or extract assets from a product page​

If your images are already on a public web page, you can skip uploading. Submit the page URL and NativeAds scrapes it, ranks what it finds by how central each image is to the page's subject, and returns candidates for review. Nothing is stored in the brand until you commit.

  1. Submit the URL — send url plus the brandId that will own the results. The call returns an extractionId; a run usually takes 30-60 seconds.

  2. Poll Get extraction until status is completed or failed. A completed extraction carries a candidates array, best first, each with a preview URL, a relevance score and a one-line reason. While it is still running there is no candidates key at all, so read it defensively.

    Each candidate also carries looksLikeLogo, the extractor's own guess that this one is the brand's logo. It is advisory. It is a different field from the isLogo you send at commit: that one is the user's decision and is what actually sets the asset's type. Use looksLikeLogo to pre-tick a box or to phrase the question, not to answer it.

  3. Commit the ones you want — post the candidate ids you chose. Sending an empty body commits every candidate the ranker kept, so if you are driving this from a user's selection, do not call the endpoint when nothing is selected: there is no commit-nothing request shape.

Committed candidates become normal assets, so the same rule as uploading applies: poll Get asset until status is complete before referencing one in generation. Mark a logo with isLogo: true on its first commit; because commit is idempotent, setting it later on an already-committed candidate is ignored. Asset type is fixed at creation and there is no endpoint that changes it, so a logo committed as a plain image has to be committed again from a fresh extraction, or uploaded directly. Ask before you send isLogo: true.

To withdraw a scrape — wrong page, or media you would rather not have held — delete the extraction. That removes it and its uncommitted staged copies; anything you already committed is a normal asset and is untouched.

API Reference: Extract from URL · Get extraction · Commit candidates · Delete extraction

3. Extract and activate Brand DNA​

Brand DNA is the platform’s model of visual and verbal identity — colors, fonts, tone, audience — learned from website URLs and/or uploaded assets. Extraction is asynchronous.

Brand DNA is a paid-plan capability. On a plan that does not include it every /brands/{brandId}/brand-dna/* endpoint answers 403, reads as well as writes, as does the legacy GET /brands/{brandId}/dna. Generation is unaffected unless you ask for Brand DNA explicitly: useBrandDna: true on a plan without it is a 403, while omitting the field simply generates without Brand DNA.

  1. Create a DNA version from urls and/or assetIds (logo + brand assets + PDFs + site together work best).
  2. Poll Get DNA version until status is ready (or failed). Re-run is also async — poll the same GET after rerun.
  3. Review confidence score and any missing fields; re-run with richer sources if it’s weak.
  4. Activate the version. Creation alone does not apply it — generation only uses an active version.

You can rename or correct DNA fields, cancel an in-flight extraction, or delete a version when needed.

API Reference: Create DNA version · Get DNA version · Activate · List versions · Active version · Update · Re-run · Cancel · Delete

4. (Optional) Enhance the prompt​

Before generating, you can send a draft prompt through enhancement. The create call returns a job id immediately.

Poll until status is completed (or failed):

Then review the optimized prompt (and theme, for images) and pass it into generation with promptIsEnhanced: true. For video enhancement, Brand DNA is off by default — pass useBrandDna: true to apply it.

API Reference: Enhance Scene Forge prompt · Enhance image-to-video prompt

5. Generate a product image (Scene Forge)​

Describe the scene in plain language (for example, “a bag of coffee on a sunlit marble kitchen counter”). Optionally pass product and environment asset IDs so the real product appears in the shot.

Scene Forge applies Brand DNA by default when an active version exists and the plan includes Brand DNA; on a plan without it, an omitted useBrandDna resolves to false rather than failing. The create call returns immediately with a job id. Poll Get Scene Forge until status is completed or failed. A completed job typically yields several image variations with download URLs.

API Reference: Create Scene Forge · Get Scene Forge · List Scene Forges

6. Generate video​

Video has two different input shapes, and the model you send decides which one is legal. Always send model explicitly: an omitted value resolves to a start-frame model, and which one that is may change.

Start-frame models turn a single still into motion. Provide a start-frame asset (often a Scene Forge output), a prompt, and dimensions; optional end or intermediate frames, duration and audio depend on the model. The start-frame asset must be complete.

seedance-2.5-pro is reference-to-video. It takes a set of reference images and/or videos rather than frames:

  • Pass referenceImageAssetIds and/or referenceVideoAssetIds — at least one reference in total.
  • It rejects startImageAssetId, endImageAssetId and intermediateImageAssetIds. Every other model rejects the two reference fields in turn, so the shapes never mix.
  • A reference image only needs status uploaded, not complete. It must be JPEG or PNG, 120MB or smaller, and an image, logo or environment asset.
  • Reference videos are MP4 or QuickTime, 200MB or smaller, 1.8-30.2s each and 30s combined.
  • Durations are restricted to 6, 8, 10, 15, 20 or 30 seconds.
  • Reference counts and duration are capped by your plan tier, and reference videos need the top tier. Over your allowance the request fails with upgrade_required rather than being trimmed.

Unlike Scene Forge, Brand DNA is off by default for video — pass useBrandDna: true when you want it applied. The create call returns a group id immediately. Poll Get video group until status is completed or failed, then download the video assets.

On a reference-to-video group, sourceAsset and each variation's previewUrl are null — there is no start frame to stand in as a poster. Your inputs come back under referenceImageAssets and referenceVideoAssets, in the order you sent them.

API Reference: Generate video · Get video group · List video groups

Endpoints not available to keys​

API keys are limited to the developer surface. Not available to keys: brand deletion, asset deletion, API-key management, campaign/theme generation, trends, and Walmart-creative submission. Those remain available to signed-in users in the app.

Troubleshooting​

SymptomWhat to check
401Missing Bearer prefix, mistyped key, or expired/revoked key
403Endpoint is outside the key’s developer surface, or the feature needs a higher plan tier (including more seedance-2.5-pro references or a longer duration than your tier allows)
422An input asset is not ready. A start-frame asset must be complete; a seedance-2.5-pro reference image needs only uploaded
Job never finishesStop polling; GET the resource once and read status / error fields
Weak or off-brand outputConfirm Brand DNA is active, and that generation requested DNA where required (especially video)
Asset / DNA / generation rejects an idConfirm the asset status is complete before referencing it (seedance-2.5-pro reference images also accept uploaded)

Next steps​

  • API Reference — full schemas and every operation a key can call
  • MCP Guide — same capabilities as tools for Claude, Cursor, ChatGPT, and custom clients
  • MCP Tool Catalog — tool-by-tool map of the workflow above