---
title: "Create a character"
method: POST
path: "/v1/characters"
tags: ["Characters"]
---

# Create a character

`POST /v1/characters`

## Request

- Base URL: `https://api.tryleap.ai`
- URL: `https://api.tryleap.ai/v1/characters`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Keeps a character from 1 to 4 pictures you uploaded (`POST /v1/files`) or made (`POST /v1/generations/{id}/outputs/{index}/file`). Leap reads its look from them once. From then on, pass its `chr_...` ID wherever a model or recipe takes an image file: a list such as `images` gets all its pictures, a single image input its first. Free; a workspace keeps up to 200.

Needs an API key with the `generations:write` scope.

## Request body

- CharacterRequest
  - `name` string, required: What you call the character, up to 40 characters. Leap never puts it in a picture unless your prompt does.
  - `images` string[], required: 1 to 4 pictures of the character, by file ID (`file_...`, from POST /v1/files or a run's result). The first one shows it; more angles keep it closer.

## Response `201`

The character.

- Character: A character your workspace keeps. Put its ID in a run's input in place of an image file, and the run gets its pictures and a description of its look, so it comes out the same every time.
  - `id` string, required: The character's ID, `chr_...`. Pass it wherever a model or recipe takes an image file.
  - `object` 'character', required
  - `beta` true, required: This endpoint is in beta: its shape can change, or it can go away, without the 180-day notice stable endpoints get.
  - `name` string, required: The character's name.
  - `images` object[], required: Its pictures, first picture first.
    - `file` string, required: The picture's file, `file_...`.
    - `url` string, uri, required: A signed link to the picture, valid for 24 hours. Read the character again for a fresh one.
    - `width` integer, nullable, required
    - `height` integer, nullable, required
  - `created_at` string, date-time, required: When it was made.
  - `updated_at` string, date-time, required: When its name or pictures last changed.

## Other responses

- `400`: `invalid_parameter`, `conflicting_credentials`
- `401`: `authentication_required`
- `403`: `permission_denied`
- `409`: `conflict`
- `429`: `rate_limit_exceeded`

---

[API](https://skmtc.dev/tryleap/apis/leap-api.md) · [All operations](https://skmtc.dev/tryleap/apis/leap-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tryleap/apis/leap-api/revisions/c01f98d3e835?raw)