Shapes are general purpose social agents. You can build for an existing shape from our catalogue of millions or create your own. Shapes have rich personalities, love hanging out in groupchats, and short-term + long-term memory across platforms.
The Shapes API enables developers to connect Shapes across social platforms, games, and other applications. Shapes can meet you anywhere, from your favorite social app or a new project. You can configure a Shape to use some of 50+ models we offer for free across text, image, and voice.
Our API is designed with extensibility as a core principle. You can extend any Shape for tool calling, MCP, and more.
Star and contribute to this repository to receive free hosting for your integration. We will also be directing traffic from our user base to your integration.
Shapes API provides a programmatic way to integrate Shapes into any application or platform. It follows the OpenAI-compatible API standard, making it easy to implement with existing libraries and SDKs.
To learn more about implementing Shapes in your app, check out our examples repository.
Shapes API comes with many features that you won’t find in general APIs. Here's a quick overview:
Shapes API supports cross-platform, long-term and short-term memory! Shapes will automatically reference relevant memories across sessions.
You can generate images directly through Shapes API — just use the !imagine command or the relevant endpoint.
Access all trending LLMs including GPT-4.1, Claude Sonnet 3.7, Gemini 2.5 Pro, and more — all through a single API. Models can be configured in the AI Engine tab on the selected Shape's dashboard.
Shapes API supports voice messages. Configure your integration to send back audio replies using the built-in voice features.
Check out the examples in the repo to learn how to use each of these features in your integration!
You will need to generate an API Key. Every API Key is tied to a specific Shape. Get yours here
import openai
shapes_client = OpenAI(
api_key="<your-API-key>",
base_url="https://api.shapes.inc/v1/",
)
response = shapes_client.chat.completions.create(
model="shapesinc/<shape-username>",
messages=[
{"role": "user", "content": "Hello"}
]
)
print(response)const openai = require("openai");
const shapes_client = new OpenAI({
apiKey: "<your-API-key>",
baseURL: "https://api.shapes.inc/v1",
});
const response = await shapes_client.chat.completions.create({
model: "shapesinc/<shape-username>",
messages: [
{ role: "user", content: "Hello" }
]
});
console.log(response);curl -X POST https://api.shapes.inc/v1/chat/completions \
-H "Authorization: Bearer <your-API-key>" \
-H "Content-Type: application/json" \
-d '{"model": "shapesinc/<shape-username>", "messages": [{ "role": "user", "content": "Hello" }]}'| Requirement | Details |
|---|---|
| Base URL | https://api.shapes.inc/v1/ |
| Model Format | shapesinc/<shape-username> |
| Authentication | Bearer token in Authorization header |
| Environment Variables | SHAPESINC_API_KEY and SHAPESINC_SHAPE_USERNAME |
| Feature | Details |
|---|---|
| Endpoints | /chat/completions |
| Rate Limits | 5 RPM (request increase here) |
| Headers | X-User-Id for user identification, X-Channel-Id for conversation context |
| Response Format | Standard OpenAI-compatible JSON response |
Shapes now support the following commands:
!reset- Reset the Shape's long-term memory!sleep- Generate a long-term on demand!dashboard- Access the Shape's dedicated dashboard for configuration!info- Get information about the shape!web- Search the web (now free for all users)!help- Get help with commands!imagine- Generate images!wack- Reset the Shape's short-term memory
| Feature | Details |
|---|---|
| Vision Support | Send OpenAI API compatible image_url with user messages |
| Tool Calling | Shapes now support tool calling and MCP functionality |
| Voice Features | Free voice for all shapes (custom or pre-made voices via shapes.inc) |
| Voice Configuration | Option to disable voice transcripts (set via shapes.inc) |
| Voice Formatting | Improved formatting for voice URLs with new line separation |
The Shapes API supports multiple types of input modalities:
You can send image URLs in the API request using this format:
{
"model": "shapesinc/your_shape",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
]
}You can send audio URLs in the API request using this format:
{
"model": "shapesinc/your_shape",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please transcribe and respond to this audio message"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://example.com/audio.mp3"
}
}
]
}
]
}Supported audio formats: mp3, wav, ogg
| Limitation | Details |
|---|---|
| No System Messages | Shape personality comes from configuration |
| No Message History | API relies on Shape's built-in memory |
| No Streaming | Only full responses are supported |
| No Parameter Control | Temperature and other settings locked to shapes.inc settings configured for the Shape |
| Multimodility support limited to 1 input only | you can only send 1 image_url or 1 audio_url with a user message. if both image and audio urls are provided, only the audio url is processed |
Note: Shapes set on Premium Engines WILL use credits when accessed via API.
- Telegram
- Revolt
- Slack
- Bluesky
- IRC
- Chess
- Voice
We're looking for developer contributions to build:
- GitHub (to review PRs)
- Threads
- Roblox
- Minecraft
- Twitch
- Microsoft Teams
- Anything you can possibly imagine
If you'd like to build an integration:
- Fork our repository
- Build your integration following our guidelines
- Submit a PR with comprehensive documentation
We are shipping new features to the Shapes API every day. Next on our list is:
| Feature | Details |
|---|---|
| Voice Recognition | Shapes can send voice messages but not hear any yet |
| Authorize with Shapes, Inc | Authenticate users via a shapes inc account |
| Free Will | Proactively take actions |
| Messaging first | Shapes can't talk first...yet |
© 2025 Shapes, Inc.