Skip to main content
WatermarksVersion: v3

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

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:socialplanner/watermarks.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3
Example:v3

Path Parameters

locationIdstringrequired

Location Id

Example:ve9EPM428h8vShlRW1KT

Body

templateIdstring

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

Example:665f1bac78fda9b6c5f48012
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.

Example:665f1bac78fda9b6c5f48099
inputMediaUrlstringrequired

Input media URL (either video or image)

Example:http://example.com/media.mp4
mimeTypestring

MIME type of the media

Available optionsimage/jpegimage/jpgimage/pngimage/gifimage/bmpimage/webpimage/tiffimage/svg+xmlimage/vnd.microsoft.iconimage/heicimage/heifvideo/mp4
Example:image/png
postIdstring

Optional post ID to associate the watermark output with

Example:ve9EPM428h8vShlRW1KT
watermarkIdstring

Optional cache key to fetch a previously-generated watermark result

Example:ve9EPM428h8vShlRW1KT
updatePostboolean

Whether to update or create the linked post after watermarking

Example:false

Response

Watermark processing initiated or cached result returned.

successbooleanrequired

Success or Failure

Example:true
statusCodenumberrequired

Status Code

Example:201
messagestringrequired

Message

Example:Created Watermark Image
resultsobject

Async processing result