Localize Ad

Localize a campaign ad image for a new market while preserving the original compositional layout.

Adapt an existing winning ad for a new culture, language, or market. The backend reproduces the exact same compositional layout — element positions, hierarchy, and structure — while localizing copy, visual references, and cultural cues for the target audience.

Endpoint

POST /api/v1/campaigns/localize-ad

Authentication

Authorization: Bearer <your_api_key>

Request parameters

You must provide exactly one of source_job_id or source_image_url as the image source.

source_job_id · string

UUID of a completed campaign_ad_generation or campaign_ad_edit job to use as the source image. Required when source_image_url is not provided.

source_image_url · string

Direct HTTPS URL of the source ad image. Required when source_job_id is not provided.

target_culture · string · required

Description of the target market or cultural vibe (e.g. "East African, Kigali vibe", "Young urban Brazil, São Paulo street culture"). This is the primary localization signal.

prompt · string

Additional instructions for the localization, such as copy changes or specific visual elements to include or avoid.

target_language · string

Target language for on-image text (e.g. "Kinyarwanda", "Brazilian Portuguese"). Inferred from target_culture when omitted.

target_currency · string

Currency symbol or code to use for any pricing shown in the ad (e.g. "RWF", "BRL"). Inferred when omitted.

brand_id · string

UUID of a stored Brand DNA record. Reinforces brand consistency during localization.

reference_images · string[]

Up to 5 additional style or character reference images. Each item can be an HTTPS URL, a data URL, or a raw base64 string.

output · object

Output controls. All subfields are optional.

Show output fields

output.aspect_ratio · string

Canvas aspect ratio. Accepted values: auto, 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9.

output.resolution · string

Pixel tier: 512, 1K, 2K, or 4K. Defaults to 1K.

output.thinking_intensity · string

Reasoning depth. Options: minimal or high.

client_reference_id · string

Your own correlation ID for workflow or agent tracing. Maximum 200 characters.

metadata · object

String map echoed into the job payload and webhook delivery. Maximum 16 keys; each value up to 500 characters.

Example request

curl

curl -X POST "https://api.trypi.ai/api/v1/campaigns/localize-ad" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4cb74a64-83f1-4fb8-96cf-1098f145008f" \
  -d '{
    "source_job_id": "11111111-2222-3333-4444-555555555555",
    "target_culture": "East African, Kigali vibe",
    "target_language": "Kinyarwanda",
    "target_currency": "RWF",
    "prompt": "Localize this ad to Kigali, keep layout identical.",
    "output": {
      "aspect_ratio": "1:1",
      "resolution": "1K",
      "thinking_intensity": "high"
    }
  }'

Response

Returns 202 Accepted immediately.

id · string

Request identifier (e.g. req_pi_...).

object · string

Always "job".

status · string

Initial status: "queued".

created_at · number

Unix timestamp of when the request was created.

data.job_id · string

UUID of the background localization job.

{
  "id": "req_pi_...",
  "object": "job",
  "status": "queued",
  "created_at": 1760000000,
  "data": {
    "job_id": "7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a"
  }
}

Polling for the result

GET /api/v1/jobs/:job_id?wait_for_completion=true&timeout_seconds=30&expand=ad

When the job is completed:

• data.ad.image_url — the localized image URL (when you use expand=ad)
• data.payload.image_url — same URL available directly on the job payload

Idempotency

Send an Idempotency-Key header to make retries safe. Replaying the same key with the same request body returns the original 202 response. Using the same key with a different body returns 409 idempotency_key_mismatch.