POST /v1/overlay

POST /v1/overlay is the only endpoint you need.

• Send asset to bake the overlay into an image or video.
• Omit asset and send width + height to get a transparent PNG overlay only.

Request

Method: POST URL: https://snapchat-text-overlay-api.com/v1/overlay Content-Type: multipart/form-data

Form fields

Field	Type	Required	Description
asset	file	No	Image (JPEG, PNG, WebP) or video (MP4, MOV, WebM)
width	number	Conditional	Required when asset is omitted
height	number	Conditional	Required when asset is omitted
text	string	*	Single caption text, max 180 characters
overlays	string	*	JSON array of overlay objects

Either text or overlays is required.

Overlays format

[
  { "text": "night one in miami", "position": 40 },
  { "text": "second line", "position": 55 }
]

Response

The response body is:

• a rendered PNG or MP4 when asset is present
• a transparent PNG when asset is omitted

Headers

Header	Description
content-type	image/png or video/mp4
content-length	File size in bytes
content-disposition	inline; filename="uuid.ext"
x-render-id	Unique render identifier
x-source-type	image or video
x-render-duration-ms	Render time in milliseconds

Examples

TypeScript

const form = new FormData();
form.append("asset", fileInput.files[0]);
form.append("text", "night one in miami");

const resp = await fetch("https://snapchat-text-overlay-api.com/v1/overlay", {
  method: "POST",
  headers: { "x-api-key": "snap_live_your_key" },
  body: form
});

const blob = await resp.blob();

Python

import requests

with open("photo.jpg", "rb") as f:
    resp = requests.post(
        "https://snapchat-text-overlay-api.com/v1/overlay",
        headers={"x-api-key": "snap_live_your_key"},
        files={"asset": f},
        data={"text": "late checkout energy"}
    )

with open("rendered.png", "wb") as out:
    out.write(resp.content)

curl

curl -X POST https://snapchat-text-overlay-api.com/v1/overlay \
  -H "x-api-key: snap_live_your_key" \
  -F "asset=@photo.jpg" \
  -F "text=late checkout energy" \
  --output rendered.png

Transparent PNG mode

curl -X POST https://snapchat-text-overlay-api.com/v1/overlay \
  -H "x-api-key: snap_live_your_key" \
  -F "width=1080" \
  -F "height=1920" \
  -F "text=hello from overlay mode" \
  --output overlay.png