Flux Pulid API Documentation

Flux Pulid API Documentation

Playground

FLUX-PuLID uses FLUX.1 [dev] and PuLID to create photorealistic images from reference photos that preserve custom likenesses. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

FLUX-PuLID fuses the power of FLUX.1 [dev] with advanced Personalized User Likeness ID (PuLID) technology, enabling consistent character identity across different scenes, outfits, and artistic styles. Whether you want to turn a photo into a fantasy elf, cyberpunk warrior, or cinematic portrait, FLUX-PuLID ensures your face stays unmistakably you.

🎨 Why it looks great

• 🧠 ID consistency: preserves facial structure, proportions, and expression across all generated images.
• 👗 Flexible restyling: change outfits, lighting, or environment — from elegant fashion to sci-fi armor.
• 🧝 Realistic transformations: morph your likeness into new worlds — elves, heroes, mecha pilots, or film characters.
• 🎥 Cinematic detail: uses FLUX’s filmic rendering core for smooth tones, accurate skin, and realistic depth of field.
• 🎭 Creative control: adjust guidance scale for balance between faithfulness and artistic freedom.

⚙️ Limits and Performance

• Max resolution: up to 1536 × 1536 px
• Input: image reference + descriptive prompt
• Output formats: jpeg, png, webp

💰 Pricing

Each image costs $0.02.

🚀 How to Use

1. 🖼️ Upload a reference image — ensure the face in the image is clear and well-lit.
2. ✍️ Write a descriptive prompt — specify the new style, outfit, or theme.
3. 🎚️ Adjust settings — size, guidance scale, seed, and output format.
4. ▶️ Click “Run” to generate your personalized image instantly.

💡 Pro Tips

• Keep the face visible and well-lit in the input image for best likeness.
• Use 3.0–4.0 guidance scale for natural balance between realism and creativity.
• Try cinematic or fantasy prompts for striking artistic results.

🧾 Notes

Please double-check your image upload URL — if there’s an issue, the preview will not appear.

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",
  "size": "1024*1024",
  "guidance_scale": 3.5,
  "seed": -1,
  "output_format": "jpeg"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-pulid" \
  -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