Skip to main content
Generate static marketing ad images asynchronously. This endpoint follows the OpenAI image generation interface and returns a job you poll for the final result.
This endpoint shares its backend with POST /api/v1/ads/generate. Both routes accept the same request body and produce identical responses. Use whichever path fits your integration style.

​
Endpoint

POST /api/v1/images/generations

​
Authentication

Authorization: Bearer <your_api_key>

​
Request parameters

​
prompt
string
required
Ad intent prompt. Describe the ad you want to generate — the audience, tone, language, and any key visual or copy requirements. Maximum 5,000 characters.
​
reference_images
string[]
Up to 6 reference images to guide the generation. 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). When provided, the backend pulls brand colors, fonts, tone, and identity context into the generation.
​
brand_identity_json
object
Inline brand identity payload. Use this when you already have brand data 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/images/generations" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4cb74a64-83f1-4fb8-96cf-1098f145008f" \
  -d '{
    "prompt": "Create a static shoe ad for French-speaking West Africa, premium but approachable, strong CTA",
    "reference_images": ["https://example.com/reference-1.jpg"],
    "output": {
      "aspect_ratio": "4:5",
      "resolution": "1K",
      "thinking_intensity": "minimal"
    }
  }'

​
Response

Returns 202 Accepted immediately. The data.job_id is the identifier you use 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": "7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a"
  }
}

​
Polling for the result

Poll the Jobs API until the job reaches a terminal status: 
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
Use wait_for_completion=true with a timeout_seconds value (up to 120) to long-poll and avoid unnecessary round trips.

​
Idempotency

Send an Idempotency-Key header with any unique string (e.g. a UUID) 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.

​
Alias route

POST /api/v1/ads/generate is a functionally identical route that targets the same backend. Use it when you prefer an explicit domain-specific path over the OpenAI-compatible surface.