Moonborn — API · portraits
Generate a scene/outfit/pose variant locked to the canonical face
Re-uses the canonical portrait as a face-identity reference and produces a new image with a different scene, outfit, pose, or custom prompt. `useMultiReference` (Pro+) injects up to 4 prior portraits as extra identity refs (Gemini supports up to 5 character refs). Idempotent on `(scene, outfit, pose)` triple.
POST/v1/personas/{id}/portrait/variants/generatescope · Bearer (API key or session JWT)
Path parameters
| Field | Type | Description |
|---|---|---|
| idreq | string | Persona id (uuid). |
Request body
| Field | Type | Description |
|---|---|---|
| scene | string | |
| outfit | string | |
| pose | string | |
| customPrompt | string | |
| useMultiReference | boolean |
Responses
200Variant generated
Body
| Field | Type | Description |
|---|---|---|
| portraitIdreq | string | |
| statusreq | string · "pending" | "generating" | "generated" | "approved" | "rejected" | "failed" | |
| storageKeyreq | string | |
| signedUrlreq | string |
402Tier disabled
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
409Canonical missing — generate canonical first
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
422Invalid body / variant spec required
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
Body
| Field | Type | Description |
|---|---|---|
| errorreq | string | |
| message | string | |
| used | number | |
| limit | number | |
| pii | string[] | |
| term | string | |
| scores | object | |
| provider | string |
503Feature not configured
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/variants/generate \
-H "Authorization: Bearer $MOONBORN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scene": "<string>",
"outfit": "<string>",
"pose": "<string>",
"customPrompt": "<string>",
"useMultiReference": false
}'TypeScript
import Moonborn from '@moonborn/sdk';
const client = new Moonborn({ apiKey: process.env.MOONBORN_API_KEY });
const result = await client.portraits.generatePortraitVariant({
id: '<id>',
scene: "<string>",
outfit: "<string>",
pose: "<string>",
customPrompt: "<string>",
useMultiReference: false,
});Python
import os
from moonborn import Moonborn
client = Moonborn(api_key=os.environ["MOONBORN_API_KEY"])
result = client.portraits.generate_portrait_variant(
id="<id>",
scene="<string>",
outfit="<string>",
pose="<string>",
custom_prompt="<string>",
use_multi_reference=False,
)