Edit Campaign

Edit a generated or existing campaign ad image with new instructions.

Edit a campaign ad image produced by POST /api/v1/campaigns/generate. You describe what to change; the backend applies your instructions while preserving the parts of the image you want to keep.

You can also chain edits: set source_job_id to a previously completed edit job (campaign_ad_edit) to iterate on a prior edit.

Endpoint

POST /api/v1/campaigns/edit

Authentication

Authorization: Bearer <your_api_key>

Request parameters

source_job_id · string · required

UUID of a completed campaign_ad_generation job to use as the image source. You can also pass the UUID of a completed campaign_ad_edit job to chain edits.

prompt · string · required

Instruction describing what to change in the image. Be specific about what should and should not change. Maximum 5,000 characters.

reference_images · string[]

Up to 6 reference images to guide the edit. Each item can be an HTTPS URL, a data URL (data:image/...;base64,...), or a raw base64 string.

brand_id · string

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

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/edit" \
  -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",
    "prompt": "Change the background to a sunset beach scene while keeping the same layout and text.",
    "output": {
      "aspect_ratio": "4:5",
      "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 edit job. Pass this as source_job_id to chain a subsequent edit.

{
  "id": "req_pi_...",
  "object": "job",
  "status": "queued",
  "created_at": 1760000000,
  "data": {
    "job_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

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 edited image URL (when you use expand=ad)
• data.payload.image_url — same URL available directly on the job payload