Skip to main content
This guide is for server-side integrations. Use your Pi API key only on trusted backends, workers, or CLI tools — never in public browser bundles.

​
Prerequisites

  • Base URL — replace https://api.example.com with your deployed API host.
  • API key — Bearer token issued via Unkey, format pi_live_....
  • TLS — always use https in production.

​
End-to-end flow

1

Extract brand DNA

POST to /api/v1/brands/extract with at least one of url, logoBase64, or imagesBase64. The response is 202 Accepted with data.job_id.
export BASE="https://api.example.com"
export API_KEY="pi_live_***"

curl -sS -X POST "$BASE/api/v1/brands/extract" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
2

Poll the job

GET /api/v1/jobs/:job_id with wait_for_completion=true to long-poll until the job reaches completed or failed. Add expand=brand to receive the brand object inline and avoid a separate fetch.
curl -sS "$BASE/api/v1/jobs/JOB_ID_HERE?wait_for_completion=true&timeout_seconds=20&expand=brand" \
  -H "Authorization: Bearer $API_KEY"
If you did not use expand=brand, fetch the brand separately with GET /api/v1/brands/:brand_id.
3

Project brand DNA for your use case

POST to /api/v1/brands/:brand_id/project with a use_case string to receive compact, use-case-specific context JSON.
curl -sS -X POST "$BASE/api/v1/brands/BRAND_ID_HERE/project" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case":"Generate shadcn-style design tokens for a SaaS dashboard."}'

​
Campaign ads

Campaign-grade static ads are available via two equivalent routes:
  • POST /api/v1/campaigns/generate
  • POST /api/v1/images/campaigns (image-style alias)
Both return 202 Accepted with data.job_id and are polled through GET /api/v1/jobs/:id. 
export BASE="https://api.example.com"
export API_KEY="pi_live_***"

curl -sS -X POST "$BASE/api/v1/campaigns/generate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Create a premium Gen Z static ad for a soft drink","output":{"aspect_ratio":"4:5","resolution":"1K"}}'

​
Next steps