Complete tutorials for using the Yemaya SDKs.
Available SDKs#
| Language | Package | Installation |
|---|---|---|
| TypeScript/JavaScript | @yemaya/sdk |
npm install @yemaya/sdk |
| Python | yemaya |
pip install yemaya |
| C++ | yemaya-cpp |
See C++ Installation |
TypeScript SDK#
Installation#
bash
npm install @yemaya/sdk
# or
pnpm add @yemaya/sdk
# or
yarn add @yemaya/sdk
Quick Start#
typescript
import { YemayaClient } from '@yemaya/sdk';
// Initialize client
const client = new YemayaClient({
apiKey: 'your-api-key',
// or use access token
// accessToken: 'your-jwt-token'
});
// Create a project
const project = await client.projects.create({
name: 'My Game',
type: 'game',
});
// Generate 3D model
const job = await client.threeD.generate({
prompt: 'A cartoon cat character',
quality: 'high',
});
// Wait for completion
const result = await job.waitForCompletion();
console.log('Model URL:', result.assets.glb);
Authentication#
typescript
// API Key authentication (recommended for server-side)
const client = new YemayaClient({
apiKey: process.env.YEMAYA_API_KEY,
});
// JWT authentication (for client-side after login)
const client = new YemayaClient({
accessToken: userSession.accessToken,
refreshToken: userSession.refreshToken,
onTokenRefresh: (tokens) => {
// Save new tokens
saveSession(tokens);
},
});
// Login to get tokens
const tokens = await YemayaClient.login({
email: 'user@example.com',
password: 'password',
});
Projects#
typescript
// List projects
const projects = await client.projects.list({
status: 'active',
type: 'game',
page: 1,
limit: 20,
});
// Create project
const project = await client.projects.create({
name: 'My New Game',
description: 'An adventure game',
type: 'game',
settings: {
targetPlatforms: ['pc', 'switch'],
gameEngine: 'godot',
},
});
// Get project
const details = await client.projects.get('proj_abc123');
// Update project
await client.projects.update('proj_abc123', {
name: 'Updated Name',
});
// Delete project
await client.projects.delete('proj_abc123');
// Duplicate project
const copy = await client.projects.duplicate('proj_abc123', {
name: 'Project Copy',
includeAssets: true,
});
Assets#
typescript
// List assets
const assets = await client.assets.list('proj_abc123', {
type: 'model',
folder: 'characters',
});
// Upload asset
const asset = await client.assets.upload('proj_abc123', {
file: fs.readFileSync('model.fbx'),
name: 'Hero Character',
folder: 'characters',
tags: ['character', 'hero'],
onProgress: (progress) => {
console.log(`Uploading: ${progress}%`);
},
});
// Download asset
const blob = await client.assets.download('proj_abc123', 'ast_abc123');
fs.writeFileSync('downloaded.fbx', blob);
// Get asset versions
const versions = await client.assets.getVersions('proj_abc123', 'ast_abc123');
// Create new version
await client.assets.createVersion('proj_abc123', 'ast_abc123', {
file: fs.readFileSync('model_v2.fbx'),
changelog: 'Updated animations',
});
3D Generation#
typescript
// Text-to-3D
const job = await client.threeD.generate({
prompt: 'A low-poly sword with glowing runes',
provider: 'meshy',
quality: 'high',
style: 'stylized',
});
// Monitor progress
job.on('progress', (progress) => {
console.log(`Progress: ${progress}%`);
});
// Wait for result
const result = await job.waitForCompletion();
// Access generated assets
console.log('GLB:', result.assets.glb);
console.log('FBX:', result.assets.fbx);
console.log('Thumbnail:', result.thumbnail);
// Image-to-3D
const imageJob = await client.threeD.generateFromImage({
image: fs.readFileSync('reference.png'),
quality: 'high',
autoRig: true,
rigType: 'humanoid',
});
// Batch generation
const batchJob = await client.threeD.batch(
[
{ prompt: 'A wooden chair' },
{ prompt: 'A wooden table' },
{ prompt: 'A wooden cabinet' },
],
{
quality: 'standard',
style: 'realistic',
}
);
const results = await batchJob.waitForCompletion();
Audio#
typescript
// Generate music
const musicJob = await client.audio.generateMusic({
prompt: 'Epic orchestral battle theme',
genre: 'orchestral',
duration: 120,
tempo: 140,
});
const music = await musicJob.waitForCompletion();
console.log('Music URL:', music.audioUrl);
// Voice synthesis
const voice = await client.audio.synthesize({
text: 'Welcome, brave adventurer!',
voiceId: 'voice_fantasy_male',
emotion: 'excited',
});
console.log('Voice URL:', voice.audioUrl);
// Generate sound effects
const sfx = await client.audio.generateSFX({
description: 'Sword clash with metallic ring',
duration: 2,
style: 'realistic',
});
NPCs#
typescript
// Create NPC
const npc = await client.npcs.create({
name: 'Elena Brightwood',
role: 'merchant',
projectId: 'proj_abc123',
personality: {
traits: ['friendly', 'shrewd'],
values: ['fairness', 'prosperity'],
},
background: {
occupation: 'General goods merchant',
history: 'Former adventurer turned shopkeeper',
},
});
// Chat with NPC
const response = await client.npcs.chat(npc.npcId, {
playerId: 'player_001',
message: 'Do you have any healing potions?',
context: {
location: 'shop',
timeOfDay: 'morning',
},
});
console.log('NPC says:', response.response);
console.log('Emotion:', response.emotion);
// Get NPC memories
const memories = await client.npcs.getMemories(npc.npcId, {
playerId: 'player_001',
limit: 10,
});
Real-Time (WebSocket)#
typescript
// Connect to WebSocket
const realtime = client.realtime();
await realtime.connect();
// Subscribe to events
realtime.subscribe('project:proj_abc123');
// Listen for events
realtime.on('asset.uploaded', (data) => {
console.log('New asset:', data.assetId);
});
realtime.on('generation.progress', (data) => {
console.log(`Job ${data.jobId}: ${data.progress}%`);
});
realtime.on('generation.completed', (data) => {
console.log('Completed:', data.jobId);
});
// Disconnect when done
realtime.disconnect();
Autonomous Pipelines#
typescript
// Create autonomous project
const autonomousProject = await client.autonomous.createProject({
type: 'game',
prompt: 'A cozy farming simulation with anime-style graphics',
autonomyLevel: 'guided',
quality: 'high',
});
// Subscribe to updates
const subscription = client.autonomous.subscribe(autonomousProject.id);
subscription.on('phaseCompleted', (phase) => {
console.log(`Completed phase: ${phase.name}`);
});
subscription.on('interventionRequired', async (intervention) => {
console.log('Intervention needed:', intervention.reason);
// Resolve intervention
await client.autonomous.resolveIntervention(intervention.id, {
selectedOption: intervention.options[0].id,
});
});
// Wait for completion
const result = await client.autonomous.waitForCompletion(autonomousProject.id);
// Download builds
const builds = await client.autonomous.getBuilds(autonomousProject.id);
Python SDK#
Installation#
bash
pip install yemaya
Quick Start#
python
from yemaya import YemayaClient
# Initialize client
client = YemayaClient(api_key="your-api-key")
# Create a project
project = client.projects.create(
name="My Game",
type="game"
)
# Generate 3D model
job = client.three_d.generate(
prompt="A cartoon cat character",
quality="high"
)
# Wait for completion
result = job.wait_for_completion()
print(f"Model URL: {result.assets['glb']}")
Authentication#
python
# API Key authentication
client = YemayaClient(api_key=os.environ["YEMAYA_API_KEY"])
# JWT authentication
client = YemayaClient(
access_token=session["access_token"],
refresh_token=session["refresh_token"]
)
# Login to get tokens
tokens = YemayaClient.login(
email="user@example.com",
password="password"
)
Projects#
python
# List projects
projects = client.projects.list(
status="active",
type="game",
page=1,
limit=20
)
for project in projects.data:
print(f"- {project.name}")
# Create project
project = client.projects.create(
name="My New Game",
description="An adventure game",
type="game",
settings={
"targetPlatforms": ["pc", "switch"],
"gameEngine": "godot"
}
)
# Update project
client.projects.update(
project_id="proj_abc123",
name="Updated Name"
)
Assets#
python
# Upload asset
with open("model.fbx", "rb") as f:
asset = client.assets.upload(
project_id="proj_abc123",
file=f,
name="Hero Character",
folder="characters"
)
# Download asset
data = client.assets.download(
project_id="proj_abc123",
asset_id="ast_abc123"
)
with open("downloaded.fbx", "wb") as f:
f.write(data)
3D Generation#
python
# Text-to-3D
job = client.three_d.generate(
prompt="A low-poly sword with glowing runes",
provider="meshy",
quality="high"
)
# Wait with progress callback
def on_progress(progress):
print(f"Progress: {progress}%")
result = job.wait_for_completion(on_progress=on_progress)
print(f"GLB: {result.assets['glb']}")
# Batch generation
batch_job = client.three_d.batch(
prompts=[
"A wooden chair",
"A wooden table",
"A wooden cabinet"
],
quality="standard"
)
results = batch_job.wait_for_completion()
Audio#
python
# Generate music
music_job = client.audio.generate_music(
prompt="Epic orchestral battle theme",
genre="orchestral",
duration=120
)
music = music_job.wait_for_completion()
print(f"Music URL: {music.audio_url}")
# Voice synthesis
voice = client.audio.synthesize(
text="Welcome, brave adventurer!",
voice_id="voice_fantasy_male",
emotion="excited"
)
Async Support#
python
import asyncio
from yemaya import AsyncYemayaClient
async def main():
client = AsyncYemayaClient(api_key="your-api-key")
# Async operations
projects = await client.projects.list()
# Concurrent generation
jobs = await asyncio.gather(
client.three_d.generate(prompt="A sword"),
client.three_d.generate(prompt="A shield"),
client.three_d.generate(prompt="A helmet")
)
# Wait for all
results = await asyncio.gather(*[
job.wait_for_completion() for job in jobs
])
asyncio.run(main())
React Integration#
useYemaya Hook#
tsx
import { useYemaya, YemayaProvider } from '@yemaya/sdk/react';
// Wrap app with provider
function App() {
return (
<YemayaProvider apiKey="your-api-key">
<MyComponent />
</YemayaProvider>
);
}
// Use in components
function MyComponent() {
const { client, isConnected } = useYemaya();
const [projects, setProjects] = useState([]);
useEffect(() => {
client.projects.list().then(setProjects);
}, [client]);
return (
<div>
<h1>Projects</h1>
{projects.map((p) => (
<div key={p.id}>{p.name}</div>
))}
</div>
);
}
useGenerate3D Hook#
tsx
import { useGenerate3D } from '@yemaya/sdk/react';
function ModelGenerator() {
const { generate, isLoading, progress, result, error } = useGenerate3D();
const handleGenerate = () => {
generate({
prompt: 'A cartoon cat',
quality: 'high',
});
};
return (
<div>
<button onClick={handleGenerate} disabled={isLoading}>
Generate
</button>
{isLoading && <p>Generating... {progress}%</p>}
{error && <p>Error: {error.message}</p>}
{result && <model-viewer src={result.assets.glb} />}
</div>
);
}
useRealtime Hook#
tsx
import { useRealtime } from '@yemaya/sdk/react';
function ProjectUpdates({ projectId }) {
const { subscribe, on } = useRealtime();
useEffect(() => {
subscribe(`project:${projectId}`);
const unsubscribe = on('asset.uploaded', (data) => {
console.log('New asset:', data);
});
return unsubscribe;
}, [projectId, subscribe, on]);
return <div>Listening for updates...</div>;
}
Error Handling#
TypeScript#
typescript
import { YemayaError, RateLimitError, ValidationError } from '@yemaya/sdk';
try {
await client.projects.create({ name: '' });
} catch (error) {
if (error instanceof ValidationError) {
console.log('Validation errors:', error.details);
} else if (error instanceof RateLimitError) {
console.log(`Retry after: ${error.retryAfter}s`);
await sleep(error.retryAfter * 1000);
} else if (error instanceof YemayaError) {
console.log(`API Error: ${error.code} - ${error.message}`);
} else {
throw error;
}
}
Python#
python
from yemaya.exceptions import (
YemayaError,
RateLimitError,
ValidationError
)
try:
client.projects.create(name="")
except ValidationError as e:
print(f"Validation errors: {e.details}")
except RateLimitError as e:
print(f"Retry after: {e.retry_after}s")
time.sleep(e.retry_after)
except YemayaError as e:
print(f"API Error: {e.code} - {e.message}")