Assets API

Upload and manage images for use in your materials. Includes AI-powered background removal and Unsplash integration.

Endpoints

Method	Endpoint	Description
POST	`/api/assets/upload`	Upload image file
POST	`/api/assets/upload-url`	Upload from URL
POST	`/api/assets/remove-background`	Remove background (AI)
POST	`/api/assets/process`	Process image
GET	`/api/assets/unsplash/search`	Search Unsplash
POST	`/api/assets/unsplash/import`	Import from Unsplash
GET	`/api/assets`	List all assets

Upload Image

POST /api/assets/upload

Upload an image to use in materials.

Request

Send as multipart/form-data:

curl -X POST https://api.adbot.fi/api/assets/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "name=Product Image"

Form Parameters

Parameter	Type	Description
`file`	file	Image file (JPG, PNG, WebP, GIF). Max 10MB.
`name`	string	Optional name for the asset
`folder`	string	Optional folder path for organization

Response

{
  "success": true,
  "data": {
    "id": "asset_abc123",
    "name": "Product Image",
    "url": "https://cdn.adbot.fi/assets/asset_abc123.png",
    "type": "image/png",
    "width": 1000,
    "height": 1000,
    "fileSize": 245632,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Upload from URL

POST /api/assets/upload-url

Upload an image from a URL.

Request Body

{
  "url": "https://example.com/images/product.png",
  "name": "Product Image from URL"
}

Response

{
  "success": true,
  "data": {
    "id": "asset_def456",
    "name": "Product Image from URL",
    "url": "https://cdn.adbot.fi/assets/asset_def456.png",
    "originalUrl": "https://example.com/images/product.png",
    "type": "image/png",
    "width": 800,
    "height": 800,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Background Removal

POST /api/assets/remove-background

Remove the background from an image using AI.

Request Body

{
  "assetId": "asset_abc123"
}

Or with a URL:

{
  "url": "https://example.com/images/product.png"
}

Response

{
  "success": true,
  "data": {
    "id": "asset_xyz789",
    "name": "Product Image (no background)",
    "url": "https://cdn.adbot.fi/assets/asset_xyz789.png",
    "type": "image/png",
    "originalAssetId": "asset_abc123",
    "backgroundRemoved": true,
    "createdAt": "2024-01-15T10:30:05Z"
  }
}

Tip: Background removal works best with product photos that have clear edges and contrasting backgrounds.

Image Processing

POST /api/assets/process

Apply transformations to an image (resize, crop, format conversion).

Request Body

{
  "assetId": "asset_abc123",
  "operations": [
    {
      "type": "resize",
      "width": 500,
      "height": 500,
      "fit": "cover"
    },
    {
      "type": "format",
      "format": "webp",
      "quality": 85
    }
  ]
}

Supported Operations

Operation	Parameters	Description
`resize`	`width`, `height`, `fit`	Resize image. Fit options: `cover`, `contain`, `fill`
`crop`	`x`, `y`, `width`, `height`	Crop to specific region
`format`	`format`, `quality`	Convert to jpg, png, or webp
`rotate`	`angle`	Rotate by degrees (90, 180, 270)

Unsplash Search

GET /api/assets/unsplash/search

Search for royalty-free images from Unsplash.

Query Parameters

Parameter	Type	Description
`query`	string	Search keywords
`page`	integer	Page number (default: 1)
`perPage`	integer	Results per page (default: 20, max: 30)
`orientation`	string	`landscape`, `portrait`, or `squarish`

Example Request

curl -X GET "https://api.adbot.fi/api/assets/unsplash/search?query=summer+beach&orientation=landscape" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "unsplash_abc123",
        "description": "Beautiful summer beach",
        "urls": {
          "raw": "https://images.unsplash.com/...",
          "full": "https://images.unsplash.com/...",
          "regular": "https://images.unsplash.com/...",
          "small": "https://images.unsplash.com/...",
          "thumb": "https://images.unsplash.com/..."
        },
        "user": {
          "name": "John Photographer",
          "link": "https://unsplash.com/@john"
        }
      }
    ],
    "total": 1500,
    "totalPages": 75
  }
}

Import from Unsplash

POST /api/assets/unsplash/import

Import an Unsplash image to your assets library.

Request Body

{
  "unsplashId": "unsplash_abc123",
  "name": "Beach Background"
}

Response

{
  "success": true,
  "data": {
    "id": "asset_imported123",
    "name": "Beach Background",
    "url": "https://cdn.adbot.fi/assets/asset_imported123.jpg",
    "source": "unsplash",
    "unsplashId": "unsplash_abc123",
    "attribution": "Photo by John Photographer on Unsplash",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Assets

GET /api/assets

List all assets in your library.

Query Parameters

Parameter	Type	Description
`folder`	string	Filter by folder path
`type`	string	Filter by type: `image`, `video`
`limit`	integer	Number of results (default: 50)