Resources

Products

Products represent the items you want to advertise. You can create products manually via the API or through the dashboard. Once created, products can be referenced in image and video generation requests.

GET /products

List all products for your team. Supports pagination.

Query Parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Product Name",
      "description": "Description",
      "category": "Category",
      "image_url": "https://...",
      "price": 29.99,
      "currency": "USD",
      "link": "https://...",
      "created_at": "2026-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 10,
    "limit": 20,
    "offset": 0
  }
}

Examples

curl https://www.adsumo.ai/api/v1/products?limit=10&offset=0 \
  -H "Authorization: Bearer adsumo_sk_..."

POST /products

Create a new product.

Request Body

Response

Returns 201 Created with the created product object.

{
  "id": "uuid",
  "name": "Product Name",
  "description": "Description",
  "category": "Category",
  "image_path": "https://...",
  "price": 29.99,
  "currency": "USD",
  "link": "https://...",
  "created_at": "2026-01-15T12:00:00Z"
}

GET /products/{id}

Get a single product by ID.

Path Parameters

Response

Returns the product object. Returns 404 Not Found if the product does not exist or does not belong to your team.

DELETE /products/{id}

Delete a product.

Path Parameters

Response

Returns 204 No Content on success. Returns 404 Not Found if the product does not exist. Returns 409 Conflict if the product has associated generations -- you must delete those generations first.

Avatars

Avatars are the AI-generated or custom faces used in talking-avatar video ads. There are two types: platform avatars (pre-made, available to all users) and custom avatars (uploaded by your team).

GET /avatars

List platform avatars. These are pre-made avatars available to all users.

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Avatar Name",
      "thumbnail_url": "https://...",
      "gender": "female",
      "age_group": "adult",
      "avatar_type": "platform"
    }
  ]
}

GET /avatars/custom

List your team's custom avatars.

Response

Returns an array of custom avatar objects with the same fields as platform avatars, plus a description field. The avatar_type field will be "custom".

POST /avatars/custom

Create a custom avatar from an image.

Request Body

Response

Returns 201 Created with the created avatar object.

{
  "id": "uuid",
  "name": "My Custom Avatar",
  "thumbnail_url": "https://...",
  "avatar_type": "custom",
  "description": "A custom avatar for product demos",
  "created_at": "2026-01-15T12:00:00Z"
}

DELETE /avatars/custom/{id}

Delete a custom avatar.

Path Parameters

Response

Returns 204 No Content on success. Returns 404 Not Found if the avatar does not exist or does not belong to your team. Returns 409 Conflict if the avatar is in use by one or more video generations.

Generations

Generations represent the output of any creation endpoint (video ads, image ads, etc). Use these endpoints to list, filter, and check the status of your generations.

GET /generations

List all generations with optional filters. Supports pagination.

Query Parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "type": "ai-video",
      "status": "completed",
      "created_at": "2026-01-15T12:00:00Z",
      "result_url": "https://..."
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 20,
    "offset": 0
  }
}

GET /generations/{id}

Get the detailed status of a single generation. Use this endpoint to poll for completion after submitting a generation request.

Path Parameters

Response

Returns the generation object with an additional details object containing type-specific information.

Note: result_url is a temporary presigned URL that expires after 1 hour. Download and store the file if you need to access it later. You can always re-poll this endpoint to get a fresh URL.

{
  "id": "uuid",
  "type": "ai-video",
  "status": "completed",
  "created_at": "2026-01-15T12:00:00Z",
  "result_url": "https://...",
  "details": {
    "prompt": "A 30-second product demo video",
    "model": "sora-2",
    "duration": 30,
    "aspect_ratio": "9:16"
  }
}

The contents of the details object vary by generation type:

• talking-avatar: avatar_id, script, voice_id, template, duration
• ai-video: prompt, model, duration, aspect_ratio
• image: prompt, model, aspect_ratio, resolution, quantity

Examples

curl https://www.adsumo.ai/api/v1/generations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer adsumo_sk_..."

Credits

GET /account/credits

Check your team's current credit balance.

Response

{
  "credits_used": 150,
  "credits_limit": 600,
  "credits_remaining": 450
}

Credit limits depend on your subscription tier. See the Overview for tier details.