Apply watermark to an image

POST 
/social-media-posting/:locationId/watermarks/add-image-watermark

Apply a watermark to an image using either a specific template ID or by resolving the template bound to a specific connected account.

If the same watermark + image combination has been processed before, the response returns immediately with status: completed and the output URL in message. Otherwise, processing is queued and the response returns status: pending with a progressId.

Rate limits: This endpoint may be rate-limited to prevent abuse. To resolve a template dynamically at publish time, pass accountId — the endpoint will resolve the template bound to that connected account. Use the Get Accounts endpoint to look up account IDs.

Processing is asynchronous — the response returns a progressId that identifies this preview job.

Document fields:

• status: 'pending' | 'processing' | 'completed' | 'failed'
• outputMediaUrl: string, available when status is completed
• errorMessage: string, available when status is failed

Request

Version stringrequired

API Version

Available optionsv3

locationId stringrequired

Location Id

application/json

application/json

Body

Bodyrequired

templateIdstring

Template ID to apply. Required if accountId is not provided.

accountIdstring

Connected account ID — the endpoint will resolve the template bound to this account. Required if templateId is not provided. Use the Get Accounts endpoint to look up account IDs.

inputMediaUrlstringrequired

Input media URL (either video or image)

mimeTypestring
MIME type of the media
Available optionsimage/jpegimage/jpgimage/pngimage/gifimage/bmpimage/webpimage/tiffimage/svg+xmlimage/vnd.microsoft.iconimage/heicimage/heifvideo/mp4
postIdstring

Optional post ID to associate the watermark output with

watermarkIdstring

Optional cache key to fetch a previously-generated watermark result

updatePostboolean

Whether to update or create the linked post after watermarking

Example (auto)

{
  "templateId": "665f1bac78fda9b6c5f48012",
  "accountId": "665f1bac78fda9b6c5f48099",
  "inputMediaUrl": "http://example.com/media.mp4",
  "mimeType": "image/png",
  "postId": "ve9EPM428h8vShlRW1KT",
  "watermarkId": "ve9EPM428h8vShlRW1KT",
  "updatePost": false
}

application/json

Watermark processing initiated or cached result returned.

application/json

Schema

Schema

successbooleanrequired

Success or Failure

statusCodenumberrequired

Status Code

messagestringrequired

Message

resultsobject

Async processing result

Example (auto)

{
  "success": true,
  "statusCode": 201,
  "message": "Created Watermark Image",
  "results": {
    "progressId": "abc123def456",
    "status": "pending",
    "message": "Watermark preview processing initiated."
  }
}