Characters API

Endpoints for managing persistent character references.

Overview

The Characters API enables creating and managing reusable character definitions for consistent multi-scene generation. Characters store appearance descriptions and reference images that can be used across unlimited sessions.

Define once, generate unlimited consistent scenes

List Characters

Retrieve all saved characters with pagination and search.

GET /api/characters

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Items per page (max: 100)
offset	integer	0	Pagination offset
search	string	-	Search name/description
sort_by	string	name	name, created, used, recent

Request

curl -X GET "https://gobananasai.com/api/characters?sort_by=used" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": [
    {
      "id": 5,
      "character_name": "Luna",
      "description": "Fantasy protagonist with magical abilities",
      "times_used": 47,
      "reference_image_count": 3,
      "created_at": "2024-01-01T00:00:00.000Z",
      "last_used_at": "2024-01-15T10:30:00.000Z",
      "thumbnail_url": "https://pub-xxx.r2.dev/..."
    },
    {
      "id": 8,
      "character_name": "Felix",
      "description": "Luna's companion, a friendly wizard",
      "times_used": 32,
      "reference_image_count": 0,
      "created_at": "2024-01-05T00:00:00.000Z",
      "last_used_at": "2024-01-14T18:45:00.000Z",
      "thumbnail_url": null
    }
  ],
  "pagination": {
    "total": 12,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Character

Retrieve full details for a specific character.

GET /api/characters/:identifier

Request

curl -X GET "https://gobananasai.com/api/characters/5" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": {
    "id": 5,
    "character_name": "Luna",
    "description": "Fantasy protagonist with magical abilities",
    "base_prompt": "A young woman with bright red hair in a long braid, emerald green eyes, freckles across her nose, wearing a brown leather adventurer's outfit with gold trim",
    "negative_prompt": "modern clothing, technology, blurry",
    "system_instruction": "Fantasy illustration style, detailed, vibrant colors",
    "reference_images": [
      {
        "id": 12,
        "url": "https://pub-xxx.r2.dev/...",
        "thumbnail_url": "https://pub-xxx.r2.dev/..."
      },
      {
        "id": 15,
        "url": "https://pub-xxx.r2.dev/...",
        "thumbnail_url": "https://pub-xxx.r2.dev/..."
      },
      {
        "id": 18,
        "url": "https://pub-xxx.r2.dev/...",
        "thumbnail_url": "https://pub-xxx.r2.dev/..."
      }
    ],
    "preferred_aspect_ratio": "portrait",
    "tags": ["fantasy", "protagonist", "female"],
    "times_used": 47,
    "created_at": "2024-01-01T00:00:00.000Z",
    "last_used_at": "2024-01-15T10:30:00.000Z"
  }
}

Create Character

Save a new character definition.

POST /api/characters

Request Body

Field	Type	Required	Description
character_name	string	Yes	Unique name (max: 100)
base_prompt	string	Yes	Appearance description (10-2000 chars)
description	string	No	Notes about character (max: 500)
negative_prompt	string	No	What to avoid (max: 1000)
system_instruction	string	No	Style guidance (max: 1000)
preferred_aspect_ratio	string	No	Default aspect ratio
reference_image_ids	integer[]	No	Up to 10 image IDs
tags	string[]	No	Up to 20 tags

Request

curl -X POST "https://gobananasai.com/api/characters" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "character_name": "Captain Aria",
    "base_prompt": "A confident woman in her 30s with short black hair and a scar across her left eyebrow, wearing a navy blue naval captain uniform with gold epaulettes and brass buttons",
    "description": "Protagonist for maritime adventure story",
    "negative_prompt": "modern clothing, casual wear",
    "system_instruction": "Historical maritime painting style",
    "preferred_aspect_ratio": "portrait",
    "reference_image_ids": [25, 28],
    "tags": ["maritime", "protagonist", "historical"]
  }'

Response

{
  "data": {
    "id": 15,
    "character_name": "Captain Aria",
    "description": "Protagonist for maritime adventure story",
    "base_prompt": "A confident woman in her 30s with short black hair and a scar across her left eyebrow, wearing a navy blue naval captain uniform with gold epaulettes and brass buttons",
    "negative_prompt": "modern clothing, casual wear",
    "system_instruction": "Historical maritime painting style",
    "reference_images": [
      {
        "id": 25,
        "url": "https://pub-xxx.r2.dev/...",
        "thumbnail_url": "https://pub-xxx.r2.dev/..."
      },
      {
        "id": 28,
        "url": "https://pub-xxx.r2.dev/...",
        "thumbnail_url": "https://pub-xxx.r2.dev/..."
      }
    ],
    "preferred_aspect_ratio": "portrait",
    "tags": ["maritime", "protagonist", "historical"],
    "times_used": 0,
    "created_at": "2024-01-15T11:00:00.000Z",
    "last_used_at": null
  }
}

Update Character

Modify an existing character.

PATCH /api/characters/:identifier

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
character_name	string	New name
base_prompt	string	Updated appearance
description	string	Updated notes
negative_prompt	string	Updated exclusions
system_instruction	string	Updated style
preferred_aspect_ratio	string	Updated aspect ratio
reference_image_ids	integer[]	Replace reference images
tags	string[]	Replace tags

Request

curl -X PATCH "https://gobananasai.com/api/characters/15" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Main protagonist for maritime adventure series",
    "reference_image_ids": [25, 28, 32, 35],
    "tags": ["maritime", "protagonist", "historical", "series-main"]
  }'

Response

{
  "data": {
    "id": 15,
    "character_name": "Captain Aria",
    "description": "Main protagonist for maritime adventure series",
    "base_prompt": "A confident woman in her 30s with short black hair and a scar across her left eyebrow, wearing a navy blue naval captain uniform with gold epaulettes and brass buttons",
    "negative_prompt": "modern clothing, casual wear",
    "system_instruction": "Historical maritime painting style",
    "reference_images": [
      { "id": 25, "url": "https://pub-xxx.r2.dev/...", "thumbnail_url": "https://pub-xxx.r2.dev/..." }
    ],
    "preferred_aspect_ratio": "portrait",
    "times_used": 0,
    "created_at": "2024-01-15T11:00:00.000Z",
    "last_used_at": null,
    "tags": ["maritime", "protagonist", "historical", "series-main"]
  }
}

Delete Character

Remove a character from the library.

DELETE /api/characters/:id

Request

curl -X DELETE "https://gobananasai.com/api/characters/15" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": { "deleted": true }
}

Note

Deleting a character does not delete images generated with it. Those images retain their character_id reference for history tracking.

Generate with Character

Generate an image featuring a saved character.

POST /api/characters/:id/generate

Request Body

Field	Type	Required	Description
scene_prompt	string	Yes	Scene description (5-1500 chars)
additional_details	string	No	Extra details (max: 500)
aspect_ratio	string	No	Override character default
override_negative_prompt	string	No	Replace character's negative prompt
session_id	string	No	Custom session ID

Request

curl -X POST "https://gobananasai.com/api/characters/5/generate" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scene_prompt": "standing on a cliff overlooking a stormy sea",
    "additional_details": "wind blowing through her hair, dramatic lighting",
    "aspect_ratio": "landscape"
  }'

Response

{
  "data": {
    "imageId": 145,
    "sessionId": "api-char-1700000000",
    "fullUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-15/generate-a1b2c3d4.png",
    "thumbnailUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-15/generate-a1b2c3d4-thumb.jpg",
    "r2Key": "acme-corp/2024-01-15/generate-a1b2c3d4.png",
    "width": 1365,
    "height": 1024,
    "format": "png",
    "sizeBytes": 524288,
    "thumbnailSizeBytes": 65536,
    "prompt": "The character from the reference images above standing on a cliff overlooking a stormy sea. Wind blowing through her hair, dramatic lighting.",
    "message": "Image generated successfully with character \"Luna\""
  }
}

Generate Multi-Character Scene

Generate an image with multiple characters together.

POST /api/characters/generate-multi

Request Body

Field	Type	Required	Description
character_ids	integer[]	Yes	2-5 character IDs
scene_prompt	string	Yes	Scene with all characters (10-1500 chars)
additional_details	string	No	Extra styling
aspect_ratio	string	No	Default: landscape
session_id	string	No	Custom session ID

Request

curl -X POST "https://gobananasai.com/api/characters/generate-multi" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "character_ids": [5, 8],
    "scene_prompt": "having a conversation in an ancient library filled with magical books",
    "additional_details": "warm candlelight, floating spell particles",
    "aspect_ratio": "16:9"
  }'

Response

{
  "data": {
    "imageId": 146,
    "sessionId": "api-multichar-1700000000",
    "fullUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-15/generate-e5f6g7h8.png",
    "thumbnailUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-15/generate-e5f6g7h8-thumb.jpg",
    "width": 1820,
    "height": 1024,
    "prompt": "Generate an image showing Character 1: Luna, Character 2: Felix together. Scene: having a conversation in an ancient library filled with magical books. Use the reference images provided to maintain each character's appearance.",
    "characterCount": 2,
    "message": "Multi-character scene generated successfully with 2 characters"
  }
}

Error Responses

400 Invalid Base Prompt

{
  "error": "Base prompt must be between 10 and 2000 characters",
  "details": ["Base prompt must be between 10 and 2000 characters"]
}

404 Character Not Found

{
  "error": "Character not found"
}

409 Duplicate Name

{
  "error": "Character \"Luna\" already exists for this tenant. Use a different name or update the existing character."
}

400 Invalid Reference Images

{
  "error": "One or more reference image IDs are invalid",
  "details": { "invalid_ids": [999, 1001] }
}

Next Steps

• Products API →
• Style Presets API →
• Usage API →