Moonborn — API · portraits
Generate the canonical portrait for a persona
Runs the Gemini 3 Pro Image pipeline using the persona layers as the prompt source. Idempotent: if a canonical already exists in `generated`/`approved` status it is returned without a new provider call. Tier-gated (Pro+); rate-limited by `persona.portrait.monthly_limit`. PII strip + celebrity blocklist enforced before the provider call.
POST/v1/personas/{id}/portrait/canonical/generatescope · Bearer (API key or session JWT)
Path parameters
| Field | Type | Description |
|---|---|---|
| idreq | string | Persona id (uuid). |
Request body
| Field | Type | Description |
|---|---|---|
| aspectRatio | string · "1:1" | "3:4" | "4:3" | "9:16" | "16:9" | default: "3:4" |
| imageSize | string · "1K" | "2K" | "4K" | default: "2K" |
| force | boolean | default: false |
Responses
200OK
Body
| Field | Type | Description |
|---|---|---|
| portraitIdreq | string | |
| statusreq | string · "pending" | "generating" | "generated" | "approved" | "rejected" | "failed" | |
| storageKeyreq | string | |
| signedUrlreq | string |
402Tier disabled (Pro+ required)
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
422PII or impersonation block
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
429Monthly quota exceeded
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
502Upstream provider error (Gemini/OpenAI)
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
503Feature not configured (env missing)
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
Examples
cURL
curl -X POST https://api.moonborn.co/v1/personas/<id>/portrait/canonical/generate \
-H "Authorization: Bearer $MOONBORN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"aspectRatio": "3:4",
"imageSize": "2K",
"force": false
}'TypeScript
import Moonborn from '@moonborn/sdk';
const client = new Moonborn({ apiKey: process.env.MOONBORN_API_KEY });
const result = await client.portraits.generateCanonicalPortrait({
id: '<id>',
aspectRatio: "3:4",
imageSize: "2K",
force: false,
});Python
import os
from moonborn import Moonborn
client = Moonborn(api_key=os.environ["MOONBORN_API_KEY"])
result = client.portraits.generate_canonical_portrait(
id="<id>",
aspect_ratio="3:4",
image_size="2K",
force=False,
)