Using Character Reference (--cref) with Midjourney API!

Posted on 2024/3/13 by GoAPI

Supporting Character Reference (--cref) in Midjourney API!

Hi everyone! As you might be aware that Midjourney has just released the long-waited 'Character Reference' feature yesterday! The new feature is similar to the previously released 'Style Reference' feature, but instead of guiding the model to match to a reference style this new feature allows users to match a specified character's looks!

So for developers like you, this feature is going to be a game changer for your users who are looking to have continuity in their creative effort (ex. their storytelling images), or if your users are just doing some simple face-swap shenanigans for fun!

And of course you can count on GoAPI supporting this feature right after its release in our Midjourney API ! So, let's take a look at how it works and the type of character-based images we could achieve with Character Reference!

A screenshot of the official Midjourney Announcement of the launch of the Character Reference feature in their Discord channel — The official Midjourney announcement of the Character Reference (--cref) feature launch

Experimenting with Character Reference

Like always, we will use Postman to test out the API as it is free to use and requires no coding experience!

First, we will send a simple imagine API call with "a boy" as the prompt. Below is the cURL code snippet taken from Postman:


  curl --location 'https://api.midjourneyapi.xyz/mj/v2/imagine' 
  --header 'X-API-Key: YOUR API KEY' 
  --header 'Content-Type: application/json' 
  --data '{
      "prompt": "a boy",
      "skip_prompt_check": false,
      "process_mode": "fast",
      "aspect_ratio": "",
      "webhook_endpoint": "",
      "webhook_secret": ""
  }'

And below is the result that I got from Midjourney.

4 images of a happy boy in a 2x2 grid generated by Midjourney — Midjourney generated images of a boy

And let's say I want to continue working with the boy's look in the fourth image, so I will do an upscale API call on it (below is the Postman cURL code snippet)


  curl --location 'https://api.midjourneyapi.xyz/mj/v2/upscale' 
  --header 'X-API-Key: YOUR API KEY' 
  --header 'Content-Type: application/json' 
  --data '{
      "origin_task_id": "enter the taskID of the previous boy imagine task",
      "index": "4",
      "webhook_endpoint": "",
      "webhook_secret": ""
  }'

an enlarged image of the previously generated image of a boy — An upscaled version of an image of a boy generated by Midjourney

Now, let's say we want to create an image of the boy playing in a school yard, we will the use the '--cref' parameter for Character Reference in our new imagine prompt and append the previously obtained image url after the parameter as shown below. I will also set the --cw parameter to 100 as I want to maintain strong reference to the face, clothing, and hair.


  curl --location 'https://api.midjourneyapi.xyz/mj/v2/imagine' 
  --header 'X-API-Key: YOUR API KEY' 
  --header 'Content-Type: application/json' 
  --data '{
      "prompt": "boy playing in schoolyard --cref https://img.midjourneyapi.xyz/mj/taskid.png --cw 100",
      "skip_prompt_check": false,
      "process_mode": "fast",
      "aspect_ratio": "",
      "webhook_endpoint": "",
      "webhook_secret": ""
  }'

4 images of a boy playing in a schoolyard in a 2x2 grid generated by Midjourney with reference to the image of the boy as the previously generated — A boy playing in a schoolyard with Character Reference to the previously-generated image of a boy

Experimenting with two URLs with --Cref

Now we can try an advanced feature of blending the character styles from two different links in the same prompt using --cref. Let's say I want to create an image where the previously generated image of the boy wearing an iron man suit and is fighting evil.

First, I found an iron man suit image from the internet.

An image of iron man suited up - to be used a character reference in the following prompt — An image of iron man suited up

Then I will use imgbb as the free service to upload this image and to get a link to it (note I will only be using the imgbb link ending in png or jpg for my subsequent prompt)

And now for my imagine API call, I will use a simple prompt 'a boy wearing an iron man suit fighting evil' with the boy's image and the image of the iron man suit as character reference, and setting the --cw parameter to 0 as I want to only focus on the boy's facial structure.


  curl --location 'https://api.midjourneyapi.xyz/mj/v2/imagine'   --header 'X-API-Key: YOUR API KEY'   --header 'Content-Type: application/json'   --data '{
      "prompt": "a boy wearing an iron man suit fighting evil --cref link1 link2 --cw 0",
      "skip_prompt_check": false,
      "process_mode": "fast",
      "aspect_ratio": "",
      "webhook_endpoint": "",
      "webhook_secret": ""
  }'

4 images of a boy in iron man suit fighting evil - as a result of combining two character reference images (the boy and the iron man suit) in one prompt — The generated images of a boy in iron-man suit fighting evil

And voila! In the output we can see the boy's blonde hair was somewhat kept, his roundish facial structure was also somewhat kept, and the iron man suit design was very well kept. Despite the fact that the likeliness of the boy in the generated image is not extremely high, but we know that prompting with generative AI models is not perfect nor an exact science; with more trials and errors I am sure we will all get a better hang of it!

And that is it for our tutorial on how to use the Character Reference (--cref) parameter to achieve consistent characters in your generated images with Midjourney API!

Happy tinkering guys!