DocsAPIIntegrations

Integrations and Ads Studio API

How to securely connect Ads Studio to your systems: issue keys, work with projects, start generation, read status, and download results.

Manage integrations Studio docs Open studio

Overview

The API uses the same entities as the UI:

Project — an ad project (format, duration, goal, assets).
Job — a generation job created from a project (queued → processing → done/error).
Outputs — job outputs (e.g. final video). File links are temporary signed URLs.

Important

Signed file links are not stored in the database and are regenerated on every job read. To get a fresh link, request the job status again.

Security and access

Integrations work in the context of a team space (company/space). This means:

All requests need the x-ads-tenant-id header — the space identifier.
API keys use the x-ads-api-key header.
Issuing and revoking keys is available only for owner and admin roles.

Keys are not stored in plain text

Only the key hash is stored in the database. The key value is shown once on creation — store it securely.

Quota and control

API keys are limited by adsApiCallsMonthly. Exceeding it returns HTTP 429.

Managing keys (in the UI)

In the company console open: Integrations. There you can create/revoke keys and see their name and fingerprint (prefix/last4).

In the UI these calls go via the Ads UI proxy → Ads API:

GET /api/space/keys → Ads API /api/ads/keys
POST /api/space/keys → Ads API /api/ads/keys
POST /api/space/keys/<id>/revoke → Ads API /api/ads/keys/<id>/revoke

Project & generation flow

Recommended order of actions for integrations:

Step 1

Find projectId

Integrations usually work with existing projects (created in the UI). Get the list via GET /api/ads/projects.

Step 2

Start generation

Create a job via POST /api/ads/generate. The response contains jobId and status queued.

Step 3

Read status and download results

Request the job via GET /api/ads/jobs/<jobId> or the project jobs list GET /api/ads/projects/<projectId>/jobs. The response contains outputs with signed URLs.

Request examples (curl)

In all examples replace:

TENANT_ID — space identifier
API_KEY — integration key

1) List projects

curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/projects

2) Start generation

curl -s   -X POST   -H "content-type: application/json"   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   -d '{
    "projectId": "PROJECT_ID",
    "brief": "Short offer and video requirements",
    "durationSec": 12,
    "aspect": "9:16"
  }'   https://YOUR_ADS_API_HOST/api/ads/generate

3) Check job status

curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/jobs/JOB_ID

4) List project jobs

curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/projects/PROJECT_ID/jobs

Uploading assets (UI flow)

In the UI, uploads work via a secure presign mechanism:

Ads UI requests a presign: POST /api/uploads/presign
Receives uploadUrl and key
Uploads the file directly to storage using PUT uploadUrl
Attaches the key to a project: POST /api/projects/<id>/assets

Security checks

The server accepts only keys like projects/<projectId>/<kind>/<uuid>.<ext>. This prevents attaching arbitrary files outside the project folder.

Ready to connect an integration?

Create a key in the company console and start by listing projects and launching your first job.

Integrations Projects