Chroma Golem API Documentation

API Keys

API keys are secure credentials that allow you to authenticate and access Chroma Golem's AI services. They enable you to implement text and image generation into your games with just a few lines of code.

Contents

Overview

API keys are unique authentication credentials that give your games access to Chroma Golem's AI services. Each API key is associated with either your personal account or an organization you belong to.

Key Features

  • Secure authentication for AI API access
  • Default AI model preferences for consistent results
  • Detailed usage analytics and monitoring
  • Shareable between team members (organization keys)
  • Support for both text and image generation

Types of API Keys

Personal API Keys

Tied to your individual account and credits. Best for solo developers or personal projects.

Organization API Keys

Shared among team members with centralized billing and usage tracking. Perfect for studios and teams.

Best Practice: Create separate API keys for different games or projects to better track and manage usage. This also limits exposure if a key needs to be revoked.

Creating API Keys

Creating Personal API Keys

Personal API keys use your individual account's credit balance and are perfect for solo developers or independent projects.

Create API Key

Name:

To create a personal API key:

  1. 1 Navigate to the API Dashboard in your account
  2. 2 Enter a descriptive name for your API key (e.g., your game name)
  3. 3 Click the Create button to generate your key

Important: Make sure you don't share your personal API keys with anyone else. Add your contributors as team members to your organization instead.

Creating Organization API Keys

Organization API keys use your organization's credit balance and can be accessed by team members with appropriate permissions.

Create Organization API Key

Organization:
Name:

To create an organization API key:

  1. 1 Navigate to the API Dashboard in your account
  2. 2 Select the organization from the dropdown menu
  3. 3 Enter a descriptive name for your API key
  4. 4 Click the Create button to generate your key

Note: You must have the appropriate permissions (admin or owner) within the organization to create API keys.

Managing API Keys

After creating API keys, you'll need to manage them throughout their lifecycle. This includes viewing, updating preferences, and occasionally revoking keys when needed.

Viewing Your API Keys

Your API keys are listed on the API Dashboard. You can see:

  • Key name and a partial view of the actual key
  • When the key was created
  • When the key was last used
  • Total tokens and cost accrued by the key
  • Organization badge for organization API keys

To view a full API key:

  1. Click on the masked API key
  2. The full key will be displayed and copied to your clipboard
Your API Keys
Name Key
My Game cg-71d8...d19e
Test Project Studio Name cg-3a9c...f27b
Filtering API Keys

If you have many API keys or belong to multiple organizations, you can filter the keys displayed:

Available Filters

  • All Keys - Shows all API keys you have access to
  • Personal - Shows only your personal API keys
  • Organization Specific - Shows API keys for a specific organization
API Key Details & Settings

Click on an API key's name to access its detailed view where you can:

  • View the complete API key
  • Update model preferences
  • View detailed usage analytics
  • Export usage data

To change model preferences:

  1. Navigate to the API key's detail page
  2. Select your preferred model from the dropdown
  3. Save your changes
API Key Details
Deleting API Keys

You may need to delete an API key if:

  • The key has been compromised
  • The project the key was used for is now complete
  • You need to better organize your keys

To delete an API key:

  1. Navigate to the API key's detail page
  2. Scroll to the bottom to find the "Danger Zone"
  3. Click the "Permanently destroy this API key" button
  4. Confirm the deletion in the dialog box
Danger Zone

This action cannot be undone. This will permanently delete this API key and break any applications using it.

Warning: Deleting an API key immediately invalidates it. Any applications or services using that key will stop working. Always update your applications with a new API key before deleting an old one.

Organization Association

API keys can be associated with either your personal account or an organization you belong to. Managing these associations allows you to control which credit pool the API key uses and who has access to manage it.

Understanding API Key Association

The organization an API key is associated with determines:

  • Billing: Which credit pool is charged for usage
  • Access: Who can view and manage the key
  • Analytics: Where usage data appears
  • Permissions: What actions are allowed with the key

Note: By default, new API keys are associated with your personal account unless you specifically select an organization during creation.

API Key Association Comparison
Personal
Organization
Credit Pool
Personal credits
Organization credits
Access Control
Only you
All organization members
Visibility
Private
Shared
Changing API Key Association

You can change which organization an API key is associated with:

  1. Navigate to the API key's details page
  2. Find the Organization Association section
  3. Click the Change Organization button
  4. Select the desired organization from the dropdown
  5. Click Save Changes

Permission Requirements:

  • You must be an owner or admin of the target organization
  • For personal keys, only you can change their association
  • For organization keys, you need admin rights in both the current and target organization
Organization Association
Currently Associated with: Personal Account

Important: Changing an API key's organization will immediately affect billing. Any future usage will be charged to the new organization's credit pool.

Organization Best Practices

Tips for Managing API Key Organizations

Project Segregation

Create separate organizations for different projects to keep billing and analytics clear and separated.

Team Structure

Align organization structure with your team structure for better access control and role management.

Environment Separation

Use personal keys for development and testing, organization keys for production environments.

Regular Audits

Periodically review organization associations to ensure keys are correctly assigned to the right entities.

Model Selection

Each API key can have preferred AI models for both text and image generation. Setting default models ensures consistent results across your game and simplifies your API calls.

Text Generation Models

Model Cost (GP per 1K tokens) Best For
o1 18 High-quality reasoning, complex tasks
gpt-4-turbo 0.09 Advanced game mechanics, complex NPCs
gpt-4o 0.09 Advanced games requiring multimodal capabilities
o1-mini 0.04 Balanced performance and cost
o3-mini 0.013 Efficient text generation with good reasoning
gpt-3.5-turbo 0.003 Basic dialogue, simple game content
gpt-4o-mini 0.0018 Cost-effective multimodal capabilities

Image Generation Models

Model Cost (GP per image) Best For
SD XL 500 High-quality game assets and illustrations

Image Generation Styles

skill_icon

item_icon

character_portrait

Setting Default Models

Each API key can have default models configured for both text and image generation:

  1. Navigate to the API key's detail page
  2. Find the "Preferred Text Model" dropdown
  3. Select your preferred model from the list
  4. Do the same for the "Preferred Image Model" if needed
  5. Save your changes

When making API requests, the system will automatically use your preferred model unless you explicitly specify a different one in your request.

Model Preferences

Current cost: 0.003 GP per 1K tokens

Current cost: 500 GP per image

Tip: Choose models based on your game's needs. For simple dialogue or item descriptions, gpt-3.5-turbo is often sufficient and cost-effective. For complex NPCs or advanced game mechanics, consider using gpt-4o or o1-mini.

Usage Analytics

Chroma Golem provides detailed analytics for each API key, allowing you to monitor usage patterns, track costs, and make informed decisions about your AI implementation.

Key Performance Metrics

Total Requests
1,257
Tokens Used
384K
Credits Spent
1,152 GP
Avg. Response Time
0.8s

Player Analytics

Track usage patterns for individual players by including the client_id parameter in your API requests.

Top 3 Players by Usage
  • player_12345 142 requests (368 GP)
  • player_67890 97 requests (215 GP)
  • player_24680 89 requests (187 GP)

Usage Over Time

Token Usage Trend
Model Usage Distribution
gpt-3.5-turbo (70%)
gpt-4o (20%)
o1-mini (10%)
Accessing Analytics

To access detailed usage analytics for your API key:

  1. Navigate to the API Keys dashboard
  2. Click on the name of the API key you want to analyze
  3. Select the Usage tab to view detailed metrics
  4. Use the date range filters to narrow down the time period
  5. View player-specific data by clicking on individual player IDs

Pro Tip: Include a unique client_id with each API request to track usage by player, level, or game feature.

Export Analytics

Download your usage data for offline analysis or reporting

Usage Insight: Analytics can help identify patterns in player behavior and optimize your credit usage. Consider implementing usage caps for individual players or monitoring for unusual spikes that might indicate inefficient prompt designs.

Security Best Practices

API keys provide direct access to your Chroma Golem account and credits. Following these security best practices helps protect your account and ensures your keys aren't misused.

API Key Security Do's

  • Use environment variables

    Store API keys in environment variables, not in your code

  • Create separate keys for different purposes

    Use distinct keys for development, testing, and production

  • Implement monitoring

    Regularly review usage analytics to detect unusual activity

  • Rotate keys periodically

    Create new keys and retire old ones on a regular schedule

  • Use secure storage

    Consider password managers or secure key vaults for storage

API Key Security Don'ts

  • Don't commit API keys to code repositories

    Never include API keys in source code or configuration files

  • Don't share API keys via unencrypted channels

    Avoid sharing keys via email, chat, or other unencrypted methods

  • Don't embed API keys in client-side code

    Never include keys in JavaScript code that runs in the browser

  • Don't use production keys for testing

    Keep development and production keys separate

  • Don't ignore unexpected usage spikes

    Investigate unusual activity immediately

Secure Implementation Examples

Server-side API Calls (Recommended) 

// Server-side environment variable
// .env file (not committed to repository)
CHROMA_GOLEM_API_KEY=cg-71d8...d19e

// Server code
require('dotenv').config();
const apiKey = process.env.CHROMA_GOLEM_API_KEY;

// Make API request
const response = await fetch('https://api.chromagolem.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: apiKey,
    messages: [{ role: 'user', content: 'Generate a sword description' }],
    client_id: 'player123'
  })
});

This approach keeps your API key secure on your server and never exposes it to the client.

Key Rotation Strategy

  1. Create a new API key with the same settings
  2. Update your environment variables or secure storage with the new key
  3. Deploy the changes to your servers
  4. Monitor to ensure the new key works correctly
  5. Delete the old API key after confirming the new one is functioning

Recommended Rotation Schedule: Rotate keys at least quarterly or immediately after team member departures or suspected security incidents.

If You Suspect a Compromised Key

  1. Immediately delete the compromised API key
  2. Create a new API key with appropriate settings
  3. Update all applications to use the new key
  4. Review usage logs to assess potential damage
  5. Contact support if unusual activity is detected
Remember: Never share your API keys with untrusted parties. Anyone with your API key can make requests using your credits.
Back to your dashboard
View my API keys