Docs

API Reference

Documentation for the Generate Ads API, allowing you to create ads programmatically.

This document provides instructions on how to use the Generate Ads API to create ads programmatically.

Authentication

All API requests must be authenticated using a Bearer token in the Authorization header. The API key must be prefixed with sk-ads-.

Example Header:

Authorization: Bearer sk-ads-xxx

Replace xxx with the actual ID of your API key. You can generate and manage your API keys in your account settings.

Endpoints

The base URL for the API is your application's domain. All endpoints are prefixed with /api/v1.

1. Create Ads

Creates one or more ads within a specified project.

Endpoint: POST /api/v1/ads
Authentication: Required.
Request Body: application/json

Parameter	Type	Required	Description
`projectId`	String	Yes	The ID of the project where the ads will be created.
`quantity`	Number	Yes	The number of ads to create. Must be greater than 0. The actual number created may be limited by available credits or a maximum cap (e.g., 20).
`mode`	String	No	The mode for ad creation ("create" or "clone").
`references`	Array	No	An array of reference image URLs or data (base64). Currently, a maximum of one reference is processed.
`audienceId`	String	No	The ID of a specific audience within the project to tailor the ads for. If not provided, a default audience may be used.
`instructions`	String	No	Specific text instructions to guide the ad generation process.

Example Request:

{
    "projectId": "project_id_example",
    "quantity": 2,
    "instructions": "Create a vibrant ad for a summer sale.",
    "size": "1080x1080",
    "references": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."]
}

const response = await fetch('https://your-app-domain.com/api/v1/ads', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer sk-ads-your_api_key_id',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        projectId: 'project_id_example',
        quantity: 2,
        instructions: 'Create a vibrant ad for a summer sale.',
        references: ['data:image/png;base64...'],
        audienceId: 'audience_id_example',
        mode: 'create'
    })
});

Success Response (200 OK): Indicates that the request to create ads was accepted and processing has begun.

{
    "success": true,
    "ads": ["adId_1", "adId_2"] // Array of IDs for the created ad entries
}

Note: Ad generation is an asynchronous process. The webhook URL (if configured in your account settings) will be notified upon completion of each ad._

2. API Status

Checks the status of the API and verifies if authentication (if provided) is successful.

Endpoint: GET /api/v1
Authentication: Optional. If an API key is provided, the identified field in the response will reflect its validity.
Response (200 OK):

{
    "success": true,
    "identified": true, // or false if no valid API key was provided
    "apiVersion": "v1"
}

const response = await fetch('https://generateads.ai/api/v1', {
    method: 'GET',
    headers: {
        Authorization: 'Bearer sk-ads-your_api_key_id',
    },
});

You can configure a webhook URL in your account settings to receive notifications when ad processing is complete. When an ad is ready, a POST request will be sent to your webhook URL with details about the ad. (Further details about the webhook payload should be added here once defined).

API Reference

Authentication

Endpoints

1. Create Ads

2. API Status

Webhooks