Overview

Introduction

The Adsumo API is a REST API that gives you programmatic access to the same AI ad generation capabilities available in the Adsumo dashboard. Create video ads, image ads, voiceovers, and more -- all from your own code or integrations.

Base URL:

https://www.adsumo.ai/api/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

Authentication

API keys are created in the Adsumo dashboard under Settings > API Keys. Each key is prefixed with adsumo_sk_ and is tied to a specific team. All generations initiated with a key will consume credits from that team's balance.

API access requires a Starter subscription tier or above.

Include your API key in the Authorization header as a Bearer token:

curl https://www.adsumo.ai/api/v1/account/credits \
  -H "Authorization: Bearer adsumo_sk_..."

Keep your API keys secret. Do not expose them in client-side code or public repositories. If a key is compromised, revoke it immediately from the dashboard and create a new one.

Async Generation Pattern

Most generation endpoints -- including video and image creation -- are asynchronous. When you submit a generation request, the API returns immediately with a generation_id and a status of "processing". The actual generation happens in the background.

You have two options for tracking completion:

1. Polling: Call GET /generations/{id} at regular intervals until the status changes to "completed" or "failed".
2. Webhooks: Configure a webhook URL to receive a POST notification when the generation finishes.

Example: Submitting a generation request

{
  "model": "sora-2",
  "prompt": "Product showcase with dynamic lighting",
  "aspect_ratio": "16:9",
  "duration": 8
}

Response (immediate):

{
  "generation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "ai-video",
  "status": "processing"
}

Polling for completion:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "ai-video",
  "status": "completed",
  "result_url": "https://cdn.adsumo.ai/...",
  "created_at": "2026-03-17T12:00:00Z"
}

Error Handling

When an error occurs, the API returns a consistent JSON structure with an error object containing a machine-readable code and a human-readable message:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your team does not have enough credits for this generation. Required: 20, available: 5."
  }
}

Error Codes

Pagination

List endpoints support pagination through two query parameters:

• limit -- Number of items to return per page (1--100, default 20).
• offset -- Number of items to skip before starting to return results (default 0).

Every paginated response includes a pagination object:

{
  "data": [ ... ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 40
  }
}

Idempotency

POST endpoints accept an optional Idempotency-Key header. If you send the same idempotency key twice within 24 hours, the API returns the original response without creating a duplicate generation or charging credits again.

This is useful for safely retrying requests when you are unsure whether the original request succeeded (for example, due to a network timeout).

curl -X POST https://www.adsumo.ai/api/v1/videos/generate \
  -H "Authorization: Bearer adsumo_sk_..." \
  -H "Idempotency-Key: my-unique-key-12345" \
  -H "Content-Type: application/json" \
  -d '{"template": "ugc", "product_id": "prod_abc123"}'

Credits

Every generation consumes credits from your team's balance. Different generation types have different credit costs -- for example, a UGC video costs more credits than a single image generation. You can check your current balance at any time:

GET /api/v1/account/credits

If a request would exceed your remaining credits, the API returns an insufficient_credits error (HTTP 402) and no generation is started. For a full breakdown of credit costs per generation type, refer to the Resources page.