Chroma Golem API Documentation

Capabilities

Generating Images

We provide a general-purpose image generation API that can be used to generate a wide variety of content for your game.

By default, we offer fine-tuned styles for characters, items, and skill icons. You can always customize your designs further with prompting. More styles and customization options are coming soon!

Customizing your generation

You're in control of the images you generate and can customize the style in the following ways:

  1. Style: This is the "base style" you start with. We've released base styles for characters, items, and skill icons.
    Tip: Styles give you a good starting place for high-quality images (they make up a model checkpoint and a LoRA specifically chosen for a type of game asset), but you can use prompts to really customize how your generations look.
  2. Prompt: This is a description of what you want to generate. You can also add your own style tags to the prompt by separating them with commas.
    Tip: Always start your prompt with what you want to generate, then add your own style tags. For example, old man blacksmith working at a medieval forge, interior blacksmithery, realistic, fantasy, dark, cinematic.
  3. Negative Prompt: This optional parameter is a description of what not to generate. If there are details you don't want to include in your image, you can add them here.
    Tip: You can add descriptions of objects, but also styles you don't want to genreate in. For example, apprentice, customers, low-poly.

Now that you understand how image prompts are constructed, you're ready to start generating images for your game!

The better your prompt, the better the output — so here are some tips for constructing a great prompt to generate the highest-quality images for your game:

  • Be specific: The more specific your prompt, the better the output. For example, instead of "main character", try "teenage adventurer, young man, blue hair, athletic build, slender, holding a scythe".

Make your API request

curl https://api.chromagolem.com/v1/image/generations \
    -H "Content-Type: application/json" \
    -d '{
    "api_key": "cg-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "client_id": "123456789",
    "prompt": "A blacksmith specializing in katanas in feudal japan.",
    "negative_prompt": "medieval, europe"
    }'

Code example

This example will make a request to our APIs directly from your console. You can use this as a starting point to integrate our APIs into your game using whatever web request library you're familiar with.

Required parameters

api_key client_id prompt

Optional parameters

negative_prompt style generation_only
Please use the table below if you require any additional information about any of these parameters. 
using System.Net.Http;
using Newtonsoft.Json;


var url = 'https://api.chromagolem.com/v1/chat/completions';
var data = new
{
    api_key = "cg-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    client_id = "123456789",
    prompt = "A blacksmith specializing in katanas in feudal japan.",
    negative_prompt = "medieval, europe"
};

var json = JsonConvert.SerializeObject(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");

using(var client = new HttpClient())
{
    var response = await client.PostAsync(url, content);
    var responseString = await response.Content.ReadAsStringAsync();
    Console.WriteLine(responseString);
}

Code example

This example will make a request to our APIs directly from your console. You can use this as a starting point to integrate our APIs into your game using whatever web request library you're familiar with.

Required parameters

api_key client_id prompt

Optional parameters

negative_prompt style generation_only
Please use the table below if you require any additional information about any of these parameters. 
import requests

url = 'https://api.chromagolem.com/v1/chat/completions'
data = {
    "api_key": "cg-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "client_id": "123456789",
    "prompt": "A blacksmith specializing in katanas in feudal japan.",
    "negative_prompt": "medieval, europe"
}

headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Code example

This example will make a request to our APIs directly from your console. You can use this as a starting point to integrate our APIs into your game using whatever web request library you're familiar with.

Required parameters

api_key client_id prompt

Optional parameters

negative_prompt style generation_only
Please use the table below if you require any additional information about any of these parameters. 
require 'net/http'
require 'json'

uri = URI('https://api.chromagolem.com/v1/chat/completions')
request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
request.body = JSON.dump({
  api_key: "cg-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  client_id: "123456789",
  prompt: "A blacksmith specializing in katanas in feudal japan.",
  negative_prompt: "medieval, europe"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts response.body

Code example

This example will make a request to our APIs directly from your console. You can use this as a starting point to integrate our APIs into your game using whatever web request library you're familiar with.

Required parameters

api_key client_id prompt

Optional parameters

negative_prompt style generation_only
Please use the table below if you require any additional information about any of these parameters. 
#include <iostream>
#include <string>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;
    std::string readBuffer;

    curl = curl_easy_init();
    if(curl) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://api.chromagolem.com/v1/chat/completions");
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"api_key\": \"cg-ABCDEFGHIJKLMNOPQRSTUVWXYZ\", \"client_id\": \"123456789\", \"messages\": [{\"role\": \"system\", \"content\": \"You are a blacksmith specializing in katanas and nodachis in a small medieval fantasy town. [...]\"}, {\"role\": \"user\", \"content\": \"What do you have for sale?\"}]}");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, "Content-Type: application/json");

        res = curl_easy_perform(curl);
        if(res != CURLE_OK)
            fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));

        curl_easy_cleanup(curl);
    }
    return 0;
}

Code example

This example will make a request to our APIs directly from your console. You can use this as a starting point to integrate our APIs into your game using whatever web request library you're familiar with.

Required parameters

api_key client_id prompt

Optional parameters

negative_prompt style generation_only
Please use the table below if you require any additional information about any of these parameters.

Request parameters

Parameter Description
Required
api_key string 		Your API key that identifies you, the developer. You can create and find your API keys on your dashboard.
Required
client_id string 		A unique client ID that refers to a specific player. This should typically be a value that is randomized for each player that does not identify them in any way, but does differentiate them from other players.
Required
prompt string 		A description of the image you want to generate. This should be as specific as possible to get the best results.
Optional
negative_prompt string 		A description of the image you don't want to generate. Great for excluding specific details or elements you don't want included.
Optional
style string 		Image generations use the style you have selected for your API key, but you can override this and use any style for a specific request by providing the desired style name here.
Optional
generation_only bool 		Defaults false. Setting this to true will omit all structure and metadata for your response, and only return the generated text as plaintext.

Parsing the response

To make working with image data easy, we've made two big design decisions for our output format:

  1. JSON format: We wrap the image data in a JSON object so you can easily parse it in your code.
    This allows us to add additional metadata to the response in the future without breaking your code. Need extra metadata for your images? Let us know!
  2. Base64 encoding: We encode the image data in base64 format so you can easily use it in your game.
    This allows you to immediately use the data for sprites, images, or textures in your code without needing to download a binary image file on your player's computer or device, and deal with read permissions or other gotchas.

With these decisions in mind, parsing the response into an image becomes a simple process:

  1. Parse the JSON: Extract the image data from the JSON object.
  2. Decode the base64: Decode the base64 data to get the image data.
  3. Use the image: Use the image data in your game.

We have some examples of this process in different languages and engines below, but once you've parsed the JSON and decoded the base64 data, you can use the image data in your game like you would any other kind of image. 

// Default request format
{
  "image": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAIAAAB7Gk...K5CYII=="
}

// Minimized request format when generation_only=true
iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAIAAAB7Gk...K5CYII==

Parsing base64 data

We respond with a simple JSON object that contains a single key, image, which contains the base64 encoded image data.

→ If you'd like your image served in a different format, please let us know on Discord.

Just give me the image data!

If you prefer to just receive your generated base64 data without the JSON structure, you can set the optional generation_only parameter to true in your request. This will remove the JSON structure and return only the base64 data as plaintext. 

/* ImageGenerationResponse class */
public class ImageGenerationResponse
{
    public string image;
}

/* Making a request and parsing the output into a usable image */

// Parse responseObject to a ImageGenerationResponse object
var response = JsonUtility.FromJson<ImageGenerationResponse>(responseObject);
byte[] imageBytes = Convert.FromBase64String(response.image);

// Create a texture with this image data
Texture2D texture = new Texture2D(2, 2);
texture.LoadImage(imageBytes);

// Create a sprite with the created texture
Sprite sprite = Sprite.Create(
    texture,
    new Rect(0.0f, 0.0f, texture.width, texture.height),
    new Vector2(0.5f, 0.5f), 100.0f
);

// Use the newly-created sprite like a normal sprite
selectedCharacter.portrait = sprite;

Parsing base64 data

We respond with a simple JSON object that contains a single key, image, which contains the base64 encoded image data.

→ If you'd like your image served in a different format, please let us know on Discord.

Just give me the image data!

If you prefer to just receive your generated base64 data without the JSON structure, you can set the optional generation_only parameter to true in your request. This will remove the JSON structure and return only the base64 data as plaintext. 

// ImageGenerationResponse struct
struct FImageGenerationResponse
{
    FString Image;

    static FImageGenerationResponse FromJson(const FString& JsonString)
    {
        FImageGenerationResponse Response;
        TSharedPtr<FJsonObject> JsonObject;
        TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(JsonString);

        if (FJsonSerializer::Deserialize(Reader, JsonObject) && JsonObject.IsValid())
        {
            JsonObject->TryGetStringField("image", Response.Image);
        }

        return Response;
    }
};

// Making a request and parsing the output into a usable texture

FImageGenerationResponse Response = FImageGenerationResponse::FromJson(ResponseString);

TArray<uint8> DecodedImageData;
FBase64::Decode(Response.Image, DecodedImageData);

UTexture2D* Texture = UTexture2D::CreateTransient(Width, Height, PF_B8G8R8A8);
void* TextureData = Texture->PlatformData->Mips[0].BulkData.Lock(LOCK_READ_WRITE);
FMemory::Memcpy(TextureData, DecodedImageData.GetData(), DecodedImageData.Num());
Texture->PlatformData->Mips[0].BulkData.Unlock();
Texture->UpdateResource();

// Use the newly-created texture
SelectedCharacter->SetPortraitTexture(Texture);

Parsing base64 data

We respond with a simple JSON object that contains a single key, image, which contains the base64 encoded image data.

→ If you'd like your image served in a different format, please let us know on Discord.

Just give me the image data!

If you prefer to just receive your generated base64 data without the JSON structure, you can set the optional generation_only parameter to true in your request. This will remove the JSON structure and return only the base64 data as plaintext. 

# ImageGenerationResponse class
class ImageGenerationResponse:
    var image: String

    func _init(data: Dictionary):
        image = data.get("image", "")

# Making a request and parsing the output into a usable texture

var json = JSON.new()
var parse_result = json.parse(response_object)
if parse_result == OK:
    var response = ImageGenerationResponse.new(json.data)
    var image_bytes = Marshalls.base64_to_raw(response.image)

    var image = Image.new()
    var error = image.load_png_from_buffer(image_bytes)
    if error == OK:
        var texture = ImageTexture.create_from_image(image)

        # Use the newly-created texture
        selected_character.set_portrait_texture(texture)
    else:
        print("Failed to load image from buffer")
else:
    print("Failed to parse JSON")

Parsing base64 data

We respond with a simple JSON object that contains a single key, image, which contains the base64 encoded image data.

→ If you'd like your image served in a different format, please let us know on Discord.

Just give me the image data!

If you prefer to just receive your generated base64 data without the JSON structure, you can set the optional generation_only parameter to true in your request. This will remove the JSON structure and return only the base64 data as plaintext. 

# ImageGenerationResponse class
class ImageGenerationResponse:
    def __init__(self, image):
        self.image = image

# Making a request and parsing the output into a usable image

import json
import base64
import pygame

# Parse responseObject to a ImageGenerationResponse object
response = json.loads(responseObject, object_hook=lambda d: ImageGenerationResponse(**d))
image_bytes = base64.b64decode(response.image)

# Create a surface with this image data
image_surface = pygame.image.fromstring(image_bytes, (width, height), 'RGBA')

# In Pygame, we don't need to create a separate sprite object
# We can use the surface directly or create a sprite if needed

# Use the newly-created surface
selected_character.portrait = image_surface

Parsing base64 data

We respond with a simple JSON object that contains a single key, image, which contains the base64 encoded image data.

→ If you'd like your image served in a different format, please let us know on Discord.

Just give me the image data!

If you prefer to just receive your generated base64 data without the JSON structure, you can set the optional generation_only parameter to true in your request. This will remove the JSON structure and return only the base64 data as plaintext. 

# ImageGenerationResponse class
class ImageGenerationResponse
  attr_accessor :image

  def initialize(image)
    @image = image
  end
end

# Making a request and parsing the output into a usable image

require 'json'
require 'base64'
require 'gosu'

# Parse responseObject to a ImageGenerationResponse object
response = JSON.parse(responseObject, object_class: ImageGenerationResponse)
image_bytes = Base64.decode64(response.image)

# Create a Gosu::Image with this image data
texture = Gosu::Image.from_blob(width, height, image_bytes)

# Use the newly-created image
selected_character.portrait = texture

Parsing base64 data

We respond with a simple JSON object that contains a single key, image, which contains the base64 encoded image data.

→ If you'd like your image served in a different format, please let us know on Discord.

Just give me the image data!

If you prefer to just receive your generated base64 data without the JSON structure, you can set the optional generation_only parameter to true in your request. This will remove the JSON structure and return only the base64 data as plaintext.

Have questions?

Need a little extra help? Join our Discord server for game devs to chat with our team and other developers.

Back to your dashboard
View my API keys