App öffnen
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
FieldTypeDescription
idreqstringPersona id (uuid).
Request body
FieldTypeDescription
aspectRatiostring · "1:1" | "3:4" | "4:3" | "9:16" | "16:9"default: "3:4"
imageSizestring · "1K" | "2K" | "4K"default: "2K"
forcebooleandefault: false

Responses

200OK
Body
FieldTypeDescription
portraitIdreqstring
statusreqstring · "pending" | "generating" | "generated" | "approved" | "rejected" | "failed"
storageKeyreqstring
signedUrlreqstring
402Tier disabled (Pro+ required)
Body
FieldTypeDescription
errorreqstring
messagestring
usednumber
limitnumber
piistring[]
termstring
scoresobject
providerstring
422PII or impersonation block
Body
FieldTypeDescription
errorreqstring
messagestring
usednumber
limitnumber
piistring[]
termstring
scoresobject
providerstring
429Monthly quota exceeded
Body
FieldTypeDescription
errorreqstring
messagestring
usednumber
limitnumber
piistring[]
termstring
scoresobject
providerstring
502Upstream provider error (Gemini/OpenAI)
Body
FieldTypeDescription
errorreqstring
messagestring
usednumber
limitnumber
piistring[]
termstring
scoresobject
providerstring
503Feature not configured (env missing)
Body
FieldTypeDescription
errorreqstring
messagestring
usednumber
limitnumber
piistring[]
termstring
scoresobject
providerstring

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,
)