---
title: "Create Character Reference"
method: POST
path: "/api/mcp/create_character_reference"
tags: ["mcp"]
---

# Create Character Reference

`POST /api/mcp/create_character_reference`

## Request

- Base URL: `https://writer.swapp1990.org` (the document declares no server; this is the origin it was published from)
- URL: `https://writer.swapp1990.org/api/mcp/create_character_reference`
- Auth: none declared

Make one cast member's reference image with your own image tools, then attach it.

Returns a brief built from the story: a prompt in the house reference
format (one square image: front full body, face close-up, back full
body; fitted tank top and compression shorts, barefoot; neutral pose
and expression), any existing images of the character to use as
identity references, generator settings (local Codex CLI first, fal
gpt-image-2.5 flare as backup), acceptance checks, and a 60-minute
upload URL. Generate the image locally, check it against brief.checks,
then PUT the file to upload.url (curl given; add ?model=<label>). The
server hosts it and sets the character's character_sheet (default) or
concept_art, replacing the previous one. No server image generation.

## Request body

- CreateCharacterReferenceInput: Brief + upload URL for one cast member's client-generated reference image.
  - `job_id` string, required: The story job ID.
  - `character_index` integer, nullable: 0-based cast index. Required unless character_name uniquely matches one cast member.
  - `character_name` string, nullable: Cast member name. Resolves character_index and guards against cast changes.
  - `asset_type` 'character_sheet' | 'concept_art': character_sheet = the full reference image scene stills use for identity; concept_art = a portrait.

## Response `200`

Successful Response

- GenericToolResponse: Fallback for tools whose payload is still being tightened.
  - `story_url` string, nullable
  - `article_url` string, nullable
  - `job_id` string, nullable
  - `status` string, nullable
  - `is_terminal` boolean, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api.md) · [All operations](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/revisions/ce5e2a89ab4d?raw)