longrun.
Add Text Overlay

Docs

Image actions / Add Text Overlay

Add Text Overlay

Use Add Text Overlay to process your inputs. Submit the request, then retrieve the run to get its result.

POSThttps://uselongrun.app/v1/image/text-overlay
Request
curl --request POST "https://uselongrun.app/v1/image/text-overlay" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --arg FILE_ID "${FILE_ID}" '{
  "inputs": {
    "file": $FILE_ID
  },
  "options": {
    "text": "example"
  }
}')"
Set up your API keyErrors and retries
Accepted · 202
{
  "id": "run_example",
  "status": "queued",
  "outputs": null,
  "error": null,
  "retry_of_run_id": null,
  "created_at": "2026-10-22T10:00:00.000Z",
  "updated_at": "2026-10-22T10:00:00.000Z"
}

The request is accepted, but processing has not finished. Retrieve the run using its ID to get the result.

Completed run · 200
{
  "id": "run_example",
  "status": "completed",
  "outputs": {
    "file": {
      "saved": false,
      "retained": false,
      "id": "file_result",
      "name": "2026-10-22_10-00-03-000.png",
      "mime_type": "image/png",
      "size": 102400,
      "category": "Image",
      "storage": "longrun",
      "url": "https://uselongrun.app/v1/files/file_result/content",
      "access": "authenticated",
      "source": "action",
      "created_at": "2026-10-22T10:00:03.000Z",
      "expires_at": "2026-10-23T10:00:03.000Z",
      "expired": false,
      "source_run_id": "run_example",
      "source_name": "Generated file"
    }
  },
  "error": null,
  "retry_of_run_id": null,
  "created_at": "2026-10-22T10:00:00.000Z",
  "updated_at": "2026-10-22T10:00:03.000Z"
}

Example result from Get a run after processing completes. File examples use temporary storage; metadata and values will vary with your inputs.

Get the run result

Request parameters

header
Idempotency-KeystringOptional

Scoped to workspace and operation; same key and payload reuses the run during its seven-day retention period. Changed payload returns 409.

Example
"receipt-1042-v1"

Maximum length: 200 characters.

Request body

Send a JSON body with the following inputs. Put processing settings inside options.

Inputs

inputs.fileImage fileRequired

The Image file to process. Upload it first and use the returned file ID.

Example
"${FILE_ID}"

Use an uploaded file ID or a supported file reference. Learn how to send files

Options

options.texttextRequired

Text to place on the result.

Example
"Confidential"

Maximum length: 2000 characters.

options.fonttextOptional

Font to use for the text watermark.

Example
"Arial"

Allowed values: Arial

options.font_sizenumberOptional

Size of the text, in pixels.

Example
24

Minimum: 4

Maximum: 256

options.colortextOptional

Color of the text watermark.

Example
"#ffffff"
options.xnumberOptional

Horizontal position, in pixels.

Example
20

Minimum: 0

Maximum: 16384

options.ynumberOptional

Vertical position, in pixels.

Example
20

Minimum: 0

Maximum: 16384

options.opacitynumberOptional

Transparency of the watermark: 0 is invisible and 1 is fully opaque.

Example
0.5

Minimum: 0

Maximum: 1

options.formattextOptional

File format of the generated output. Choose an allowed extension below.

Example
"png"

Allowed values: png jpeg webp

Delivery

outputobjectOptional

Choose where the result is delivered. Omit this to use temporary LongRun storage.

Example
{
  "storage": "temporary"
}

Storage guide · Bubble delivery setup

Show child fields
output.storagestringOptional

temporary stores results in LongRun. bubble delivers them to a connected Bubble app. These are the only supported values. A published workflow uses its configured destination unless you override it.

Example
"temporary"

Default: "temporary"

Allowed values: temporary bubble

output.connection_idstringConditionally required

Required when storage is bubble. Copy the connection ID from Settings → Integrations → Bubble. Not used for temporary storage.

Example
"${STORAGE_CONNECTION_ID}"
output.privatebooleanOptional

Only for Bubble delivery. true creates a private file and requires attach_to. false requests a public upload; access still depends on the receiving app configuration.

Example
false

Default: false

output.attach_tostringConditionally required

Required when storage is bubble and private is true. The Bubble Thing ID that owns the file. See the Bubble integration guide for setup.

Example
"${BUBBLE_THING_ID}"
output.file_namestringOptional

Optional output filename, such as receipt.pdf. Omit it to use the generated timestamp-based name. Applies to either destination.

Example
"receipt.pdf"

Maximum length: 255 characters.

webhook_idsarray of stringOptional

IDs of configured webhook endpoints to notify for this run. Omit this to send no webhooks for a direct action.

Example
[
  "${WEBHOOK_ID}"
]

Returns

Returns 202 Accepted with a run ID. Processing continues after the response. Retrieve the run until its status is completed, failed, or cancelled.

Retrieve a run →

Outputs when completed

These fields appear inside outputs on the completed run.

outputs.fileImage file

Generated file metadata. Use its id to retrieve or download the file; check access and expiry metadata before using its URL.

Limits

Input file
100 MiB
Generated files
200 MiB maximum
Processing deadline
120 seconds; processing may stop earlier if a renderer or resource limit is reached
Input image pixels
40 million maximum per image
Input image dimensions
16,384 pixels maximum per side; single-frame PNG, JPEG or WebP