Ideogram AI Ideogram Character API Documentation

Ideogram AI Ideogram Character API Documentation

Playground

Ideogram Character creates consistent characters from one reference image, in many styles, and supports inpainting to place the character into existing images. Ready-to-use REST API, no coldstarts, affordable pricing.

Features

Edit a single character image with text instructions. Ideogram Character is designed for changing outfits, appearance details, and visual styles based on the uploaded source image while keeping the character recognizable.

Why It Looks Great

• Character-focused editing
  Modify a character directly from a single source image while retaining key visual traits.

• Style modes
  Choose from Auto, Fiction, or Realistic styles to match your creative direction.

• Rendering speed options
  Balance speed and quality with Turbo, Default, or Quality modes.

• Flexible aspect ratios
  Choose from five output formats for different layouts.

Parameters

How to Use

1. Write your edit instruction — Describe the changes you want, such as outfit, appearance, or style.
2. Use Prompt Enhancer optional — Refine your instruction for clearer editing direction.
3. Upload one source image — Provide the character image you want to edit.
4. Choose style — Select Auto, Fiction, or Realistic based on the desired look.
5. Select rendering speed — Choose Turbo for speed, Quality for final detail, or Default for balance.
6. Set aspect ratio — Pick the output format that fits your use case.
7. Run — Generate the edited character image.
8. Download — Preview and save your result.

Pricing

Pricing varies by rendering speed.

Examples

Best Use Cases

• Fashion and outfit changes — Swap clothing, change colors, or modify accessories.
• Character design — Create variations of a character with different looks.
• Portrait editing — Adjust appearance details based on the uploaded source image.
• Style exploration — Transform a character between realistic and fictional aesthetics.
• Content creation — Generate outfit, look, or character variations for creative projects.

Example Prompts

• “Change her outfit to a red dress while keeping the lighting natural.”
• “Change the shirt to a blue business suit.”
• “Add sunglasses and a leather jacket.”
• “Transform the character into a fantasy warrior with armor.”
• “Change the hair color to blonde and keep everything else the same.”
• “Dress the character in a casual summer outfit with a white t-shirt and jeans.”

Style Guide

Pro Tips for Best Results

• Be specific about what to change and what to preserve.
• Use Realistic style for fashion and portrait edits.
• Use Fiction style for fantasy, stylized, or creative character looks.
• Start with Turbo mode to test the prompt, then switch to Quality for final output.
• Describe outfit changes clearly, including color, style, material, and accessories.
• For better consistency, use a clear source image and keep the requested changes focused.
• Match aspect ratio to your intended platform: 1:1 for profiles, 9:16 for stories, and 16:9 for banners.

Notes

• This endpoint uses a single source image for character editing. Separate character-reference and target-image inputs are not supported.
• If using a URL for the image, ensure it is publicly accessible.
• enable_base64_output is only available through the API.
• Processing time varies by rendering speed selection.
• Enable Safety Checker for content that will be publicly shared.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "style": "Auto",
  "rendering_speed": "Default",
  "aspect_ratio": "1:1"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/ideogram-ai/ideogram-character" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters