Safety & DetectionWatermarking

Apply Watermark

Beta: Watermark API is currently in beta. Please contact us if you would like to be added to the beta program.

Apply a watermark to an audio, image, or video file using the provided URL. The media type is automatically detected from the file content.

POST https://app.resemble.ai/api/v2/watermark/apply

Request Parameters

FieldTypeRequiredDescription
urlstring✅HTTPS URL to the media file (audio, image, or video).
strengthnumber❌Watermark strength for image/video (0.0-1.0, default: 0.2). Ignored for audio.
custom_messagestring❌Custom message to embed for image/video (default: “resembleai”). Ignored for audio.

Headers

HeaderValueDescription
AuthorizationBearer YOUR_API_TOKENRequired. Your API token.
Content-Typeapplication/jsonRequired.
PreferwaitOptional. When set, the API processes synchronously and returns the completed result.

Examples

Audio

$curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "url": "https://example.com/audio/source.wav"
>  }'

Image (synchronous)

$curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  -H 'Prefer: wait' \
>  --data '{
>    "url": "https://example.com/images/photo.png",
>    "strength": 0.2,
>    "custom_message": "resembleai"
>  }'

Video

$curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "url": "https://example.com/videos/clip.mp4",
>    "strength": 0.5
>  }'

Response

1{
2  "success": true,
3  "item": {
4    "uuid": "JOB_UUID",
5    "media_type": "image",
6    "source_media_url": "https://example.com/images/photo.png",
7    "metrics": null,
8    "watermarked_media": null,
9    "created_at": "2024-01-01T00:00:00.000Z",
10    "updated_at": "2024-01-01T00:00:00.000Z"
11  }
12}

When the Prefer: wait header is set, watermarked_media will contain the signed URL to the watermarked file in the initial response. Without the header, processing is asynchronous and you must poll the result endpoint.

Fetch Apply Result

Retrieve the result of an applied watermark using the provided UUID.

GET https://app.resemble.ai/api/v2/watermark/apply/{uuid}/result

Example

$curl --request GET 'https://app.resemble.ai/api/v2/watermark/apply/JOB_UUID/result' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json'

Response

1{
2  "success": true,
3  "item": {
4    "uuid": "JOB_UUID",
5    "media_type": "image",
6    "source_media_url": "https://example.com/images/photo.png",
7    "watermarked_media": "https://app.resemble.ai/rails/active_storage/...",
8    "metrics": null,
9    "created_at": "2024-01-01T00:00:00.000Z",
10    "updated_at": "2024-01-01T00:00:00.000Z"
11  }
12}

Response Fields

FieldTypeDescription
successbooleanIndicates whether the operation was successful.
item.uuidstringUnique identifier for the watermark job.
item.media_typestringDetected media type: audio, image, or video.
item.source_media_urlstringThe original source URL provided in the request.
item.watermarked_mediastringSigned URL to the watermarked file. null while processing.
item.created_atstringTimestamp of when the job was created.
item.updated_atstringTimestamp of when the job was last updated.

Important: The signed watermarked_media URL expires; download and store the asset promptly.

Error Handling

If the request is unsuccessful, you will receive an error response:

1{
2  "success": false,
3  "error": "File must be valid media format"
4}

Ensure that you provide a valid HTTPS URL pointing to a supported media file.