API Reference Documentation

Base Information

Base URL:

https://api.media.pizi.app/

Authentication:

All requests require an API key provided in the Authorization header:

Authorization: Bearer {apiKey}

Headers (global):

Content-Type: application/json
X-Credits-Remaining: {int}

Models

`POST /models`

Create a new AI model (virtual human). A model can be generated in three ways:

From characteristics only (attributes: gender, age, ethnicity, etc.)
From reference images only (one or more images)
Hybrid — combining reference images and specific attributes (images + attributes)

The API automatically determines which mode to use based on the provided payload.

Request Body (example — hybrid)

{
  "name": "Model 2025-10-28",
  "gender": "female",
  "attributes": {
    "ethnicity": "European \\ Northern European \\ Irish",
    "age": "young adult",
    "bodyType": "slim",
    "breastSize": "small",
    "hairColor": "blonde",
    "hairLength": "medium",
    "eyeColor": "green",
    "height": "medium",
    "distinctiveFeatures": ["freckles", "small moles"]
  },
  "referenceImages": [
    "https://cdn.example.com/uploads/ref1.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "metadata": {
    "project": "AutumnCollection",
    "note": "First test model"
  },
  "callbackUrl": "https://client.app/webhooks/model-complete"
}

Request Fields

Field	Type	Required	Description
`name`	string (max 100)	No	Optional custom model name (if omitted defaults to `Model {DateTime}`)
`gender`	string	Yes (see behavior)	`male` or `female`. Required for attribute-based generation; recommended in hybrid.
`attributes`	object	Optional	Detailed physical characteristics (see attributes table below)
`referenceImages`	array[string]	Optional	URLs or base64-encoded images (`data:image/png;base64,...`)
`metadata`	object	Optional	Custom user-defined tags/keys
`callbackUrl`	string	Optional	Webhook endpoint to receive completion notification
`priority`	string	Optional	`standard` (default), `high` — affects queue priority (billing may differ)

Parameters are case-insensitive in values where applicable.

Attributes (`attributes` object)

Use camelCase names. Below are supported attributes and allowed values (defaults indicated).

Attribute	Type	Allowed values / notes
`age`	string	`Baby`, `Child`, `Teenager`, `Young adult`, `Adult` (default), `Middle-aged`, `Senior`, `Elderly`
`ethnicity`	string	Hierarchical values allowed (see Appendix). Examples: `European`, `European \ Northern European`, `European \ Northern European \ Irish`
`bodyType`	string	`Slim`, `Athletic`, `Muscular`, `Average` (default), `Curvy`, `Overweight`
`height`	string	`Short`, `Medium` (default), `Tall`
`breastSize`	string	`Small`, `Medium`, `Large` (recommended only for female models)
`hairLength`	string	`Bald`, `Buzz cut`, `Short`, `Medium`, `Long`, `Very long`
`hairColor`	string	`Black`, `Dark brown`, `Brown`, `Light brown`, `Blonde`, `Platinum blonde`, `Ginger`, `Gray`, `White`
`eyeColor`	string	`Brown`, `Blue`, `Green`, `Hazel`, `Gray`, `Amber`
`facialHair`	string	`Clean-shaven`, `Mustache`, `Beard`, `Long Beard`, `Stubble` (recommended for male models)
`distinctiveFeatures`	array[string]	`Freckles`, `Small moles`, `Vitiligo`, `Rosacea`, `Cheek dimple`, `Chin dimple`, `Acne`, `Wrinkles`, `Facial scar`, `Arm scar`, `Face birthmark`, `Arm birthmark`, `Neck birthmark`, `Facial tattoo`, `Neck tattoo`, `Chest tattoo`, `Sleeve tattoo`, `Henna patterns`, `Ear piercings`, `Nose piercing`, `Lip piercing`, `Eyebrow piercing`

Behavior / Mode selection

If only referenceImages is provided → model is created from images.
If only attributes is provided → model is created from characteristics.
If both are provided → hybrid mode: attributes refine the model produced from image data.
gender is required when attributes are used to create a model. If referenceImages only are provided, gender may be omitted (model is inferred from the images).
If name omitted → server generates Model {YYYY-MM-DD HH:MM:SS} (UTC timestamp).
The model creation process is asynchronous. The endpoint returns a task.uuid to monitor progress via /tasks or by callbackUrl.

Response

{
  "success": true,
  "data": {
    "taskUuid": "b6e7a1b9-f421-45f3-9c18-22f1c63c1138"
  }
}

Supported Image Formats

The images provided via referenceImages must be in one of the following formats:

image/jpeg
image/jpg
image/png
image/webp
image/avif

Validation & limits

name length: max 100 characters.
Max number of referenceImages per request: 3.
attributes values are case-insensitive but prefer the canonical values listed above.
Requests that violate format or exceed quotas will return error responses (see Error Responses).

`GET /models`

List all persistent models belonging to the authenticated user.

Query Parameters

Name	Type	Description
`page`	integer	Page number (default `1`)
`limit`	integer	Items per page (default `50`)
`filter`	string	Full-text search over metadata (e.g. `filter=project:Autumn`)
`status`	string	`processing`, `completed`, `failed`, `deleted`

Response

{
  "success": true,
  "data": [
    {
      "uuid": "b6e7a1b9-f421-45f3-9c18-22f1c63c1138",
      "name": "Model 2025-10-28",
      "status": "completed",
      "metadata": {
        "project": "AutumnCollection"
      },
      "createdAt": "2025-10-28T08:00:00Z",
      "updatedAt": "2025-10-28T08:01:00Z"
    }
  ]
}

`GET /models/{uuid}`

Retrieve detailed information about a specific model.

Response

{
  "success": true,
  "data": {
    "uuid": "b6e7a1b9-f421-45f3-9c18-22f1c63c1138",
    "status": "completed",
    "name": "Asian Female Slim Model",
    "gender": "female",
    "attributes": {
      "ethnicity": "Asian",
      "age": "young adult",
      "bodyType": "slim",
      "hairColor": "black",
      "hairLength": "medium"
    },
    "mediaUrl": "https://maia.s3.gra.io.cloud.ovh.net/pizi-media/user-uuid/models/b6e7a1b9.png",
    "metadata": {
      "project": "AutumnCollection"
    },
    "createdAt": "2025-10-28T08:00:00Z",
    "updatedAt": "2025-10-28T08:01:00Z"
  }
}

`DELETE /models/{uuid}`

Delete a specific model and all associated generated data (permanent action).

Response

{
  "success": true,
  "code": 200,
  "message": "Model deleted successfully."
}

Pictures

`POST /pictures`

Generates one or multiple product photos using:

one or more product images
a model (existing by uuid or inline attributes)
a defined shotType

Request Body (example)

{
  "shotType": "lifestyle",
  "variants": 3,
  "model": {
    "uuid": "b6e7a1b9-f421-45f3-9c18-22f1c63c1138"
  },
  "product": {
    "images": [
      "https://example.com/image1.jpg",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    ],
    "info": "# Premium T-Shirt\n\n- Material: 100% organic cotton\n- Color: Navy blue\n- Style: Modern casual\n- Price: $29.99"
  },
  "output": {
    "aspectRatio": "16:9",
    "format": "png"
  },
  "metadata": {
    "campaign": "Winter2025",
    "productCategory": "apparel"
  },
  "callbackUrl": "https://yourapp.com/callback"
}

Request Fields

Field	Type	Required	Description
`shotType`	string	Yes	`packshot`, `studio`, `lifestyle`, `mix`
`variants`	integer	No	Number of variants: `1`, `3`, `5` for standard types; `9` for mix (default: 1 for standard, 9 for mix)
`model`	object	Optional	Either `uuid` (existing) or inline model attributes (same schema as POST /models)
`modelImageUrl`	string	Optional	URL string for the model image (mutually exclusive with `model`)
`product.images[]`	array[string]	Yes	URLs or base64-encoded images
`product.info`	string	No	Product details (Markdown or text)
`output.aspectRatio`	string	No	`1:1`(default), `9:16`, `16:9`, `3:4`, `4:3`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`
`output.format`	string	No	`png`(default), `jpg`
`metadata`	object	No	Arbitrary key/value pairs
`callbackUrl`	string	No	Webhook URL for async completion notification

Response

{
  "success": true,
  "data": {
    "taskUuid": "3f37b31f-9029-4c72-9b34-0171d60a8922"
  }
}

Supported Image Formats:

The images provided via product.images[] must be in one of the following formats:

image/jpeg
image/jpg
image/png
image/webp
image/avif

Validation & limits

Each URL in product.images[] must be publicly accessible
Images should be properly formatted and not corrupted
Maximum file size: 10 MB per image
Large images may take longer to process
Maximum of 3 images can be provided per request

`GET /pictures`

List all generated photos.

Query Parameters

Name	Type	Description
`page`	int	Page number
`limit`	int	Items per page
`filter`	string	Metadata full-text filter
`status`	string	`queued`, `processing`, `completed`, `failed`
`shotType`	string	Filter by generation type

Response

{
  "success": true,
  "data": [
    {
      "uuid": "3f37b31f-9029-4c72-9b34-0171d60a8922",
      "shotType": "creative",
      "status": "completed",
      "metadata": {
        "campaign": "Winter2025"
      },
      "createdAt": "2025-10-28T08:00:00Z"
    }
  ]
}

`GET /pictures/{uuid}`

Retrieve detailed information about a specific model.

Response

{
  "success": true,
  "data": {
    "uuid": "3f37b31f-9029-4c72-9b34-0171d60a8922",
    "shotType": "creative",
    "status": "completed",
    "variants": 3,
    "result": [
      "https://cdn.example.com/results/3f37b31f_1.png",
      "https://cdn.example.com/results/3f37b31f_2.png",
      "https://cdn.example.com/results/3f37b31f_3.png"
    ],
    "output": {
      "aspectRatio": "16:9",
      "format": "png"
    },
    "modelUuid": "b6e7a1b9-f421-45f3-9c18-22f1c63c1138",
    "metadata": {
      "campaign": "Winter2025"
    },
    "createdAt": "2025-10-28T08:00:00Z"
  }
}

Tasks

`GET /tasks`

List all generation tasks (model and photo). Useful to track progress and costs.

Response

{
  "success": true,
  "data": [
    {
      "uuid": "3f37b31f-9029-4c72-9b34-0171d60a8922",
      "type": "photo",
      "status": "completed",
      "resourceUrl": "/photos/3f37b31f-9029-4c72-9b34-0171d60a8922",
      "createdAt": "2025-10-28T08:00:00Z"
    },
    {
      "uuid": "2c92d9b2-33c4-4c1e-9d90-38e3d0e83f15",
      "type": "model",
      "status": "completed",
      "resourceUrl": "/models/b6e7a1b9-f421-45f3-9c18-22f1c63c1138",
      "createdAt": "2025-10-28T07:55:00Z"
    }
  ]
}

`GET /tasks/{uuid}`

Retrieve full details about a specific generation task.

Response

{
  "success": true,
  "data": {
    "uuid": "3f37b31f-9029-4c72-9b34-0171d60a8922",
    "type": "photo",
    "status": "completed",
    "resourceUrl": "/photos/3f37b31f-9029-4c72-9b34-0171d60a8922",
    "metadata": {
      "campaign": "Winter2025"
    },
    "createdAt": "2025-10-28T08:00:00Z",
    "completedAt": "2025-10-28T08:01:22Z"
  }
}

Error Responses

Code	Message	Description
400	`Missing or invalid parameter.`	The payload or a field is incorrect
401	`Invalid API Key.`	Authentication failed
402	`Insufficient credits.`	Not enough credits to start the task
404	`Resource not found.`	UUID does not exist
415	`Unsupported image format. Only JPG and PNG are allowed.`	One or more uploaded reference images are in an invalid format
429	`Rate limit exceeded.`	Too many requests in a short time
500	`Internal server error.`	Unexpected backend error

Async Callbacks

When a task completes (model or photo), the API sends a POST request to the provided callbackUrl with application/json.

Example Payload

{
  "taskUuid": "3f37b31f-9029-4c72-9b34-0171d60a8922",
  "resourceUrl": "https://api.media.pizi.app/v1/photos/3f37b31f-9029-4c72-9b34-0171d60a8922"
}

The callback is retried on non-2xx responses (exponential backoff, up to configured retry policy).

Implementation notes & recommendations

Use HTTPS for all requests.
Limit callbackUrl to trusted endpoints.
Monitor X-Credits-Remaining header to handle low-credit flows.
Default outputs are PNG for model result thumbnails and product photos unless output.format is specified.
If referenceImages are used to create a model, prefer front/side/back shots where possible — better results.

Appendix: Ethnicity Hierarchy (canonical values)

Use the hierarchical strings when you want fine-grained ethnicity selection (backslash \ is the delimiter). Examples shown; full list below.

African
African \ Afro-American
African \ Afro-Brazilian
African \ Afro-Caribbean
African \ Afro-Caribbean \ Haitian
African \ Afro-Caribbean \ Jamaican
African \ Afro-Caribbean \ Trinidadian
African \ Afro-Latino
African \ Central African
African \ Central African \ Cameroonian
African \ Central African \ Congolese
African \ Central African \ Gabonese
African \ East African
African \ East African \ Ethiopian
African \ East African \ Kenyan
African \ East African \ Somali
African \ East African \ Tanzanian
African \ North African
African \ North African \ Algerian
African \ North African \ Egyptian
African \ North African \ Moroccan
African \ North African \ Tunisian
African \ Southern African
African \ Southern African \ Mozambican
African \ Southern African \ South African
African \ Southern African \ Zimbabwean
African \ West African
African \ West African \ Ghanaian
African \ West African \ Ivorian
African \ West African \ Nigerian
African \ West African \ Senegalese

American
American \ Afro-American
American \ Afro-Latino
American \ Caribbean
American \ Caribbean \ Cuban
American \ Caribbean \ Dominican
American \ Caribbean \ Puerto Rican
American \ Hispanic
American \ Hispanic \ Argentinian
American \ Hispanic \ Brazilian
American \ Hispanic \ Chilean
American \ Hispanic \ Colombian
American \ Hispanic \ Mexican
American \ Hispanic \ Peruvian
American \ Native American
American \ Native American \ First Nations
American \ Native American \ Inuit

Asian
Asian \ Central Asian
Asian \ Central Asian \ Kazakh
Asian \ Central Asian \ Turkmen
Asian \ Central Asian \ Uzbek
Asian \ East Asian
Asian \ East Asian \ Chinese
Asian \ East Asian \ Japanese
Asian \ East Asian \ Korean
Asian \ Middle Eastern
Asian \ Middle Eastern \ Arab
Asian \ Middle Eastern \ Armenian
Asian \ Middle Eastern \ Iranian
Asian \ Middle Eastern \ Kurdish
Asian \ Middle Eastern \ Persian
Asian \ Middle Eastern \ Turkish
Asian \ South Asian
Asian \ South Asian \ Bangladeshi
Asian \ South Asian \ Indian
Asian \ South Asian \ Nepali
Asian \ South Asian \ Pakistani
Asian \ South Asian \ Sri Lankan
Asian \ Southeast Asian
Asian \ Southeast Asian \ Cambodian
Asian \ Southeast Asian \ Filipino
Asian \ Southeast Asian \ Indonesian
Asian \ Southeast Asian \ Malaysian
Asian \ Southeast Asian \ Thai
Asian \ Southeast Asian \ Vietnamese

European
European \ Caucasian (default)
European \ Eastern European
European \ Eastern European \ Czech
European \ Eastern European \ Hungarian
European \ Eastern European \ Polish
European \ Eastern European \ Russian
European \ Eastern European \ Slovak
European \ Eastern European \ Ukrainian
European \ Northern European
European \ Northern European \ British
European \ Northern European \ Finnish
European \ Northern European \ Irish
European \ Northern European \ Scandinavian
European \ Southern European
European \ Southern European \ Greek
European \ Southern European \ Italian
European \ Southern European \ Portuguese
European \ Southern European \ Spanish
European \ Western European
European \ Western European \ Belgian
European \ Western European \ Dutch
European \ Western European \ French
European \ Western European \ German
European \ Western European \ Swiss

Oceanian
Oceanian \ Australian Aboriginal
Oceanian \ Pacific Islander
Oceanian \ Pacific Islander \ Fijian
Oceanian \ Pacific Islander \ Hawaiian
Oceanian \ Pacific Islander \ Maori
Oceanian \ Pacific Islander \ Melanesian
Oceanian \ Pacific Islander \ Micronesian
Oceanian \ Pacific Islander \ Polynesian
Oceanian \ Pacific Islander \ Samoan
Oceanian \ Pacific Islander \ Tongan

API Reference Documentation

Base Information

Models

POST /models

Request Body (example — hybrid)

Request Fields

Attributes (attributes object)

Behavior / Mode selection

Response

Supported Image Formats

Validation & limits

GET /models

Query Parameters

Response

GET /models/{uuid}

Response

DELETE /models/{uuid}

Response

Pictures

POST /pictures

Request Body (example)

Request Fields

Response

Supported Image Formats:

Validation & limits

GET /pictures

Query Parameters

Response

GET /pictures/{uuid}

Response

Tasks

GET /tasks

Response

GET /tasks/{uuid}

Response

Error Responses

Async Callbacks

Example Payload

Implementation notes & recommendations

Appendix: Ethnicity Hierarchy (canonical values)

`POST /models`

Attributes (`attributes` object)

`GET /models`

`GET /models/{uuid}`

`DELETE /models/{uuid}`

`POST /pictures`

`GET /pictures`

`GET /pictures/{uuid}`

`GET /tasks`

`GET /tasks/{uuid}`