Skip to main content
Generate premium static campaign ads. This endpoint runs a stricter, higher-quality pipeline than POST /api/v1/images/generations — it performs mandatory corpus retrieval from the data layer and applies a six-step internal workflow before producing an image.
POST /api/v1/images/campaigns is an alias of this endpoint. Both routes share the same request schema, async lifecycle, and job polling path.

​
Endpoint

POST /api/v1/campaigns/generate

​
Authentication

Authorization: Bearer <your_api_key>

​
Request parameters

​
prompt
string
required
Generation intent. Describe the campaign ad you want — brand, audience, market, tone, and any visual or copy requirements. Maximum 5,000 characters.
​
reference_images
string[]
Up to 6 reference images. Each item can be an HTTPS URL, a data URL (data:image/...;base64,...), or a raw base64 string. Max 15 MB per image; accepted types: JPEG, PNG, WebP.
​
brand_id
string
UUID of a stored Brand DNA record (from POST /api/v1/brands/extract). Pulls brand colors, fonts, tone, and identity into the generation.
​
brand_identity_json
object
Inline brand identity payload. Use this when you have brand data on hand and do not need a stored brand record.
​
output
object
Output controls. All subfields are optional.
​
client_reference_id
string
Your own correlation ID for workflow or agent tracing. Echoed into the job record. 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 -X POST "https://api.trypi.ai/api/v1/campaigns/generate" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4cb74a64-83f1-4fb8-96cf-1098f145008f" \
  -d '{
    "prompt": "Generate a Gen Z Coca Cola static ad for summer vibes in Paris",
    "reference_images": ["https://example.com/ref1.jpg"],
    "brand_id": "11111111-2222-3333-4444-555555555555",
    "output": {
      "aspect_ratio": "4:5",
      "resolution": "1K",
      "thinking_intensity": "high"
    }
  }'

​
Response

Returns 202 Accepted immediately. Use data.job_id to poll for the result.
​
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 job. Use this to poll for results.
{
  "id": "req_pi_...",
  "object": "job",
  "status": "queued",
  "created_at": 1760000000,
  "data": {
    "job_id": "11111111-2222-3333-4444-555555555555"
  }
}

​
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 generated image URL (when you use expand=ad)
  • data.payload.image_url — same URL available directly on the job payload
To edit the image after generation, pass the returned job_id as source_job_id to POST /api/v1/campaigns/edit.

​
Alias route

POST /api/v1/images/campaigns routes to the same backend. Use it if you prefer a path that mirrors the OpenAI images namespace.