The official Python SDK for the Yemaya platform - end-to-end movie and game creation with AI-powered tools.
Installation#
bash
pip install yemaya
For CLI support:
bash
pip install yemaya[cli]
Quick Start#
Synchronous Usage#
python
from yemaya import YemayaClient
# Initialize client (reads API key from YEMAYA_API_KEY env var)
client = YemayaClient()
# Or provide API key directly
client = YemayaClient(api_key="your-api-key")
# Create a project
project = client.projects.create(
name="My Game",
type="game",
description="An awesome game project"
)
# Work with project resources
ctx = client.project(project.id)
# Create assets
asset = ctx.assets.create(
name="Hero Character",
type="character"
)
# Create scenes
scene = ctx.scenes.create(
name="Level 1",
description="The first level"
)
# Create characters
character = ctx.characters.create(
name="Hero",
role="main",
personality={
"traits": ["brave", "curious"],
"motivations": ["save the world"]
}
)
# Use AI generation
response = client.ai.generate_text(
prompt="Write a backstory for a medieval knight",
model="claude-3-sonnet"
)
print(response.result)
# Close the client when done
client.close()
Context Manager#
python
from yemaya import YemayaClient
with YemayaClient(api_key="your-api-key") as client:
projects = client.projects.list()
for project in projects.data:
print(f"{project.name} ({project.type})")
Async Usage#
python
import asyncio
from yemaya import AsyncYemayaClient
async def main():
async with AsyncYemayaClient(api_key="your-api-key") as client:
# Create a project
project = await client.projects.create(
name="My Async Project",
type="movie"
)
# Work with resources
ctx = client.project(project.id)
scenes = await ctx.scenes.list()
# AI generation
response = await client.ai.generate_image(
prompt="A majestic castle at sunset",
model="dalle-3"
)
print(f"Generated image: {response.generation.output_url}")
asyncio.run(main())
CLI Usage#
The Yemaya CLI provides command-line access to the platform:
bash
# Login with your API key
yemaya auth login
# List projects
yemaya projects list
# Create a project
yemaya projects create --name "My Project" --type game
# Generate content with AI
yemaya ai generate --prompt "Write a game story" --type text
# List assets in a project
yemaya assets list --project proj_123
Configuration#
Environment Variables#
YEMAYA_API_KEY- Your Yemaya API keyYEMAYA_BASE_URL- API base URL (default: https://api.yemaya.dev)YEMAYA_WS_URL- WebSocket URL (default: wss://api.yemaya.dev/ws)YEMAYA_DEBUG- Enable debug logging (1, true, yes)YEMAYA_TIMEOUT- Request timeout in secondsYEMAYA_MAX_RETRIES- Maximum retry attempts
Programmatic Configuration#
python
from yemaya import YemayaClient, YemayaConfig
from yemaya.config import TimeoutConfig, RetryConfig
config = YemayaConfig(
api_key="your-api-key",
base_url="https://custom.api.example.com",
timeout=TimeoutConfig(read=60.0, connect=10.0),
retry=RetryConfig(max_retries=5),
debug=True,
)
client = YemayaClient(config=config)
API Resources#
Projects#
python
# List projects
projects = client.projects.list(page=1, per_page=20)
# Get a project
project = client.projects.get("proj_123")
# Create a project
project = client.projects.create(
name="My Project",
type="game",
description="Project description",
tags=["rpg", "fantasy"]
)
# Update a project
project = client.projects.update(
"proj_123",
name="Updated Name",
status="active"
)
# Delete a project
client.projects.delete("proj_123")
# Duplicate a project
copy = client.projects.duplicate("proj_123", name="Project Copy")
# Archive a project
project = client.projects.archive("proj_123")
Assets#
python
ctx = client.project("proj_123")
# List assets
assets = ctx.assets.list(type="texture")
# Upload a file
asset = ctx.assets.upload(
file="/path/to/file.png",
name="Background Texture",
type="texture"
)
# Download an asset
content = ctx.assets.download("asset_123")
# Get asset versions
versions = ctx.assets.get_versions("asset_123")
Scenes#
python
ctx = client.project("proj_123")
# List scenes
scenes = ctx.scenes.list()
# Create a scene
scene = ctx.scenes.create(
name="Opening Scene",
settings={"ambientColor": "#404040"}
)
# Add objects to a scene
obj = ctx.scenes.add_object(
scene_id="scene_123",
name="Player Spawn",
position={"x": 0, "y": 0, "z": 0}
)
# Reorder scenes
ctx.scenes.reorder(["scene_3", "scene_1", "scene_2"])
Characters#
python
ctx = client.project("proj_123")
# Create a character
character = ctx.characters.create(
name="Hero",
role="main",
appearance={
"height": 1.8,
"hairColor": "brown"
},
personality={
"traits": ["brave", "kind"],
"backstory": "A young adventurer..."
}
)
# Generate a backstory with AI
character = ctx.characters.generate_backstory(
"char_123",
style="dramatic",
length="detailed"
)
AI Generation#
python
# Text generation
response = client.ai.generate_text(
prompt="Write a fantasy story opening",
model="claude-3-opus",
temperature=0.7
)
# Image generation
response = client.ai.generate_image(
prompt="A magical forest",
model="dalle-3",
style="fantasy",
aspect_ratio="16:9"
)
# Code generation
response = client.ai.generate_code(
prompt="Create a player movement script",
language="python"
)
# List available models
models = client.ai.list_models()
Error Handling#
python
from yemaya import YemayaClient
from yemaya.exceptions import (
YemayaError,
YemayaAPIError,
YemayaAuthenticationError,
YemayaNotFoundError,
YemayaRateLimitError,
YemayaValidationError,
)
try:
client = YemayaClient()
project = client.projects.get("invalid_id")
except YemayaNotFoundError as e:
print(f"Project not found: {e}")
except YemayaAuthenticationError as e:
print(f"Authentication failed: {e}")
except YemayaRateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
except YemayaValidationError as e:
print(f"Validation error: {e.errors}")
except YemayaAPIError as e:
print(f"API error [{e.status_code}]: {e.message}")
except YemayaError as e:
print(f"SDK error: {e}")
Development#
bash
# Clone the repository
git clone https://github.com/yemaya/yemaya
cd libs/yemaya/sdk-python
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Type checking
mypy src/yemaya
# Linting
ruff check src/yemaya
License#
MIT License - see LICENSE for details.