Create Character

Create private reusable Prism characters with local image uploads or public image URLs, then use them as consistent subjects in API generation workflows.

POST /api/characters

Creates a character owned by the authenticated user and returns the created character object.

Characters created with this endpoint are always private (isPublic: false) and are scoped to the same API key owner.

Request body

Field	Type	Required	Description
name	string	Yes	Character name (1-60 chars)
description	string	No	Optional character description (max 300 chars)
images	array<string>	Yes (JSON)	1-10 HTTP(S) image URLs
images or images[]	file	Yes (multipart)	1-10 local image files

Supported image sources:

• multipart/form-data local file uploads (images or images[])
• JSON HTTP(S) image URLs (images)

Not supported:

• Base64 / data URI values
• Direct S3 keys

JSON request (image URLs)

curl -X POST "https://www.prismvideos.com/api/characters" \
  -H "Authorization: Bearer prism_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Spokesperson",
    "description": "Warm, confident presenter with studio lighting",
    "images": [
      "https://images.example.com/person-front.jpg",
      "https://images.example.com/person-side.jpg"
    ]
  }'

Multipart request (local uploads)

curl -X POST "https://www.prismvideos.com/api/characters" \
  -H "Authorization: Bearer prism_sk_your_key_here" \
  -F "name=Product Spokesperson" \
  -F "description=Warm, confident presenter with studio lighting" \
  -F "images[]=@./person-front.png" \
  -F "images[]=@./person-side.png"

Response

201 Created

{
  "data": {
    "id": "d2a7e0d5-1705-43b5-be96-85b9c5f25b80",
    "name": "Product Spokesperson",
    "description": "Warm, confident presenter with studio lighting",
    "created_at": 1773361092291
  }
}

Response fields

Character object

Field	Type	Description
id	string	Unique character identifier
name	string	Character name
description	string or null	Character description
created_at	number	Unix timestamp in milliseconds

Errors

Status	Error	When
400	validation_error	Missing/invalid name, unsupported image source, or image count out of range
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks templates:read scope
500	server_error	Unexpected server error while creating character

See Errors for the full error reference.