Getting Started

Welcome to Inworld Studio REST API!

Studio REST API reduces friction for game developers with a robust and flexible tool that mirrors the functionality of our Inworld Studio and creates a time-saving short-cut for custom character creation. Studio REST API enables developers to leverage their existing tools for asset creation and management, introducing a simple and efficient way to use Inworld’s Studio functionalities.

In this guide, we'll walk you through the steps to get started with programmatically creating Studio assets via API.

Design Time

Studio REST API empowers game developers to build characters on the client side through programmatic character creation and moderation. Developers can use the API to make requests to the Inworld AI server from any development environment.

This facilitates batch imports, updates, or deletions of multiple assets simultaneously. The process automates the updating of character core descriptions, knowledge, common knowledge, and more, while also creating workspaces for each player automatically.

Runtime

Studio REST API also enables players, or end users, to create custom characters as user-generated content during gameplay. Players can customize the personalities, behavior, and dialogue of their own AI NPCs (non-playable characters). In a fantasy role-playing game, players could design AI companions with specialized knowledge to assist them in their quests. Or, in a city-building simulation, players could shape the dynamics and narrative of their virtual cities with unique AI citizens.

This API gives creators an easy-to-use tool to empower their players to contribute to the game world in a unique and creative way, fostering deeper immersion and engagement.

---

Authentication

Inworld Studio API uses Studio API keys to authenticate requests. You can view and manage your API keys at Inworld Studio.

Endpoints

Root endpoint for all requests: https://api.inworld.ai/studio/v1.

Request Header Values

Name	Required for	Description	Sample values
Authorization	Every request.	“Basic “ + {Base64-encoded authorization signature}	Basic ZXhh8TBsZT9rZXlfcheyaW5nOmV4Y1234GVfc2VjcmV0X3N0cmuuZw==
Grpc-Metadata-X-Authorization	Every Request.	The value studio_api indicates a constant identifier used for Studio API authentication.	studio_api

Authentication Method: HTTP Basic Authentication

HTTP Basic Authentication is a simple authentication scheme that uses the Authorization header in the HTTP request to send credentials. This method is widely supported by HTTP clients and servers.

To authenticate a request, include the Authorization header in the request with the value Basic {credentials}. The {credentials} consists of the Base64-encoded string of the API key and the secret in the format key:secret.

There are multiple ways to generate a Base64-encoded authorization signature:

• Follow the instructions here to find your Studio API key, secret, and the Base64-encoded authorization signature from Inworld Studio.
• You can also use libraries or packages like requests.auth.HTTPBasicAuth to generate a Base64-encoded authorization signature from the API key and secret.

For example, to authenticate as a user with the key "john" and secret "secret123", the Authorization header would be:

Authorization: Basic am9objpzZWNyZXQxMjM=

The Base64-encoded string am9objpzZWNyZXQxMjM= represents the key "john" and secret "secret123".

Python Sample Authentication Request

The following is a python example of using the HTTPBasicAuth class from the requests.auth package to pass the authorization credentials:

import requests
from requests.auth import HTTPBasicAuth

BASE_URL = 'https://api.inworld.ai/studio/v1'
WORKSPACE_ID = 'Your workspace ID'
STUDIO_API_KEY = 'Your Studio API Key'
STUDIO_API_SECRET = 'Your Studio API Secret'

headers = {
    'Content-Type': 'application/json',
    'Grpc-Metadata-X-Authorization-Bearer-Type': 'studio_api'
}

response = requests.get(
    url=f"{BASE_URL}/workspaces/{WORKSPACE_ID}/characters",
    headers=headers,
    auth=HTTPBasicAuth(STUDIO_API_KEY, STUDIO_API_SECRET)
)

In this example, the HTTPBasicAuth class is used to provide the auth parameter with the API key and secret. The requests library handles the Base64 encoding and sets the Authorization header automatically.

Generating a Studio API Key

info

Please note that Studio API keys are associated with your user account and are different from the Integration API keys used for runtime SDKs (see FAQ for additional information regarding the differences between the two API keys).

To authorize your requests, you'll need an API key & secret pair from your Inworld account.

Follow these steps to retrieve them:

1. Log into Inworld Studio.
2. Click on your profile photo to see a menu.
3. Under "Manage account", click on "Studio API key".
4. In the pop-up modal, you can find a Studio API key/secret pair, as well as the Base64 authorization signature.

You will be using this key in the authorization header of all requests.

security

Please note that it is VERY important that you keep both of API key and secret confidential. Anyone who has access to the key/secret pair will be able to make requests to your account and characters. If you suspect a compromise, delete the key/secret pair immediately from the Studio console and generate a new one.

---

Making your first request

Now that you have your API key and secret ready, it's time to make your first requests to interact with the AI characters.

Create your character

In this example, we'll show you how to quickly create and deploy a new character using the API.

Note: To converse and interact with a character, the character must be deployed after creation.

Request Type: POST
Request URL:

https://api.inworld.ai//studio/v1/workspaces/{workspace_id}/characters

Parameters

Name	Description	Example value
name	Unique user-generated resource name of the agent character.	"Axeon the Enchanted"
default_character_description	Structured default character description.	{ "character_role": "Warrior", "description": "Likes to fight."}

See Characters for a full list of available parameters.

Sample Request

Curl

curl -X POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters \
-H 'Content-Type: application/json' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type': 'studio_api' \
-H 'Authorization: Basic {YOUR_KEY_HERE}' \
-d '{"defaultCharacterDescription": {"givenName":"Axeon the Enchanted", "characterRole": "Warrior", "description": "Axeon is a warrior who loves to fight in battles with his axe."}}'

Python

import requests
from requests.auth import HTTPBasicAuth

BASE_URL = 'https://api.inworld.ai/studio/v1'
WORKSPACE_ID = 'Your Workspace ID'
STUDIO_API_KEY = 'Your Studio API Key'
STUDIO_API_SECRET = 'Your Studio API Secret'

char_dict = {
    "defaultCharacterDescription": {
        # Required, character name resource will be generated based on provided givenName.
        "givenName": "Axeon the Enchanted",
        "description": "Axeon is a warrior who loves to fight in battles with his axe.",
        "characterRole": "Warrior"
        }
    }

headers = {
    'Content-Type': 'application/json',
    'Grpc-Metadata-X-Authorization-Bearer-Type': 'studio_api'
}

response = requests.post(
    url=f"{BASE_URL}/workspaces/{WORKSPACE_ID}/characters",
    json=char_dict,
    headers=headers,
    auth=HTTPBasicAuth(STUDIO_API_KEY, STUDIO_API_SECRET)
    )

Deploy your character

Now that we've created a character, we'll go ahead and deploy it using the API:

Request Type: POST
Request URL:

https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}:deploy

The message body of the request is empty as it is passed through as query parameters.

Sample Request

Curl

curl -X POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/characters/{character_name}:deploy \
-H 'Content-Type: application/json' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type': 'studio_api' \
-H 'Authorization: Basic {YOUR_KEY_HERE}'

---