Generate 3D models, textures, and animations using AI-powered tools.
Overview#
The 3D Generation API enables creation of 3D assets from text prompts, images, or existing meshes. It supports multiple generation methods and output formats optimized for game engines and film production.
Base Path: /v1/3d
Authentication: Bearer token required
Endpoints Summary#
| Method | Path | Description |
|---|---|---|
| POST | /generate/text |
Generate 3D model from text prompt |
| POST | /generate/image |
Generate 3D model from image(s) |
| POST | /generate/sketch |
Generate 3D model from sketch |
| GET | /jobs/{jobId} |
Get generation job status |
| GET | /jobs/{jobId}/result |
Get generation result |
| DELETE | /jobs/{jobId} |
Cancel generation job |
| GET | /jobs |
List generation jobs |
| POST | /mesh/process |
Process/optimize mesh |
| POST | /mesh/retopology |
Retopologize mesh |
| POST | /mesh/decimate |
Reduce mesh polygon count |
| POST | /mesh/uv-unwrap |
Generate UV mapping |
| POST | /texture/generate |
Generate textures for mesh |
| POST | /texture/upscale |
Upscale texture resolution |
| POST | /texture/pbr |
Generate PBR texture set |
| POST | /rig/auto |
Auto-rig character mesh |
| POST | /rig/retarget |
Retarget animation to rig |
| POST | /animation/generate |
Generate animation from description |
| GET | /providers |
List available AI providers |
| GET | /styles |
List available generation styles |
| GET | /presets |
List generation presets |
Text-to-3D Generation#
Generate from Text#
Create a 3D model from a text description.
POST /v1/3d/generate/text
Authorization: Bearer <token>
Content-Type: application/json
{
"prompt": "A medieval knight in full plate armor, battle-worn, detailed engravings",
"negativePrompt": "low quality, blurry, deformed",
"style": "realistic",
"category": "character",
"provider": "hunyuan",
"format": "glb",
"resolution": "high",
"polyCount": "medium",
"generateTextures": true,
"textureResolution": 2048,
"generateRig": true,
"rigType": "humanoid",
"seed": 12345,
"projectId": "proj_abc123",
"callbackUrl": "https://your-server.com/webhook"
}
Request Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
prompt |
string | Yes | Text description of the desired 3D model |
negativePrompt |
string | No | Elements to avoid in generation |
style |
string | No | Generation style (see styles endpoint) |
category |
string | No | Asset category: character, creature, prop, vehicle, environment, architecture, weapon, clothing, furniture, organic, mechanical, abstract |
provider |
string | No | AI provider: hunyuan, meshy, tripo, csm (default: best available) |
format |
string | No | Output format: glb, gltf, fbx, obj, usd (default: glb) |
resolution |
string | No | Quality level: draft, standard, high, ultra |
polyCount |
string | No | Polygon budget: low (<10k), medium (10-50k), high (50-200k), ultra (200k+) |
generateTextures |
boolean | No | Generate textures (default: true) |
textureResolution |
number | No | Texture size: 512, 1024, 2048, 4096 |
generateRig |
boolean | No | Auto-rig if character/creature |
rigType |
string | No | Rig skeleton type: humanoid, quadruped, custom |
seed |
number | No | Random seed for reproducibility |
projectId |
string | No | Associate with project |
callbackUrl |
string | No | Webhook URL for completion notification |
Response (202 Accepted):
{
"success": true,
"data": {
"jobId": "job_3d_abc123",
"status": "pending",
"message": "3D generation job queued",
"estimatedTime": 120,
"queuePosition": 3
}
}
Generation Styles:
| Style | Description |
|---|---|
realistic |
Photorealistic rendering |
stylized |
Stylized/artistic look |
cartoon |
Cartoon/cel-shaded |
low_poly |
Low-polygon aesthetic |
anime |
Anime/manga style |
pbr |
Physically-based rendering optimized |
sculpted |
High-detail sculpt look |
hand_painted |
Hand-painted texture style |
Generate from Image#
Create a 3D model from one or more reference images.
POST /v1/3d/generate/image
Authorization: Bearer <token>
Content-Type: application/json
{
"images": [
{
"url": "https://example.com/front.jpg",
"view": "front"
},
{
"url": "https://example.com/side.jpg",
"view": "left"
}
],
"reconstructionMode": "multiview",
"prompt": "High-quality game asset",
"format": "glb",
"generateTextures": true
}
Request Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
images |
array | Yes | Array of image objects |
images[].url |
string | Yes | Image URL (https or data URI) |
images[].view |
string | No | View angle: front, back, left, right, top, bottom, perspective |
reconstructionMode |
string | No | Mode: single (one image), multiview (multiple angles), turntable (video) |
prompt |
string | No | Additional guidance for generation |
removeBackground |
boolean | No | Auto-remove image background |
format |
string | No | Output format |
generateTextures |
boolean | No | Generate textures from images |
Response: Same as text-to-3D
Job Management#
Get Job Status#
Check the status of a generation job.
GET /v1/3d/jobs/{jobId}
Authorization: Bearer <token>
Response:
{
"success": true,
"data": {
"jobId": "job_3d_abc123",
"status": "processing",
"progress": 45,
"stage": "generating_mesh",
"stages": [
{ "name": "queued", "completed": true, "duration": 5000 },
{ "name": "generating_mesh", "completed": false, "progress": 60 },
{ "name": "generating_textures", "completed": false },
{ "name": "post_processing", "completed": false }
],
"estimatedTimeRemaining": 65,
"createdAt": "2024-01-15T10:00:00Z",
"startedAt": "2024-01-15T10:00:05Z"
}
}
Job Statuses:
| Status | Description |
|---|---|
pending |
Job is queued |
processing |
Currently generating |
completed |
Successfully completed |
failed |
Generation failed |
cancelled |
Job was cancelled |
Get Job Result#
Retrieve the generated 3D model.
GET /v1/3d/jobs/{jobId}/result
Authorization: Bearer <token>
Response:
{
"success": true,
"data": {
"jobId": "job_3d_abc123",
"status": "completed",
"model": {
"url": "https://cdn.yemaya.io/3d/job_3d_abc123/model.glb",
"format": "glb",
"fileSize": 15000000,
"polyCount": 45000,
"vertexCount": 48000,
"materialCount": 3,
"boundingBox": {
"min": [-1.0, 0.0, -0.5],
"max": [1.0, 2.0, 0.5]
}
},
"textures": [
{
"type": "diffuse",
"url": "https://cdn.yemaya.io/3d/job_3d_abc123/diffuse.png",
"resolution": 2048
},
{
"type": "normal",
"url": "https://cdn.yemaya.io/3d/job_3d_abc123/normal.png",
"resolution": 2048
},
{
"type": "roughness",
"url": "https://cdn.yemaya.io/3d/job_3d_abc123/roughness.png",
"resolution": 2048
}
],
"rig": {
"type": "humanoid",
"boneCount": 65,
"url": "https://cdn.yemaya.io/3d/job_3d_abc123/rig.json"
},
"preview": {
"thumbnail": "https://cdn.yemaya.io/3d/job_3d_abc123/thumb.png",
"turntable": "https://cdn.yemaya.io/3d/job_3d_abc123/turntable.mp4"
},
"metadata": {
"provider": "hunyuan",
"generationTime": 95000,
"seed": 12345,
"prompt": "A medieval knight..."
},
"createdAt": "2024-01-15T10:00:00Z",
"completedAt": "2024-01-15T10:01:35Z"
}
}
List Jobs#
Get a list of generation jobs.
GET /v1/3d/jobs?status=completed&limit=20
Authorization: Bearer <token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
status |
string | Filter by status |
projectId |
string | Filter by project |
category |
string | Filter by asset category |
page |
number | Page number |
limit |
number | Items per page |
Cancel Job#
Cancel a pending or processing job.
DELETE /v1/3d/jobs/{jobId}
Authorization: Bearer <token>
Mesh Processing#
Process Mesh#
Apply processing operations to an existing mesh.
POST /v1/3d/mesh/process
Authorization: Bearer <token>
Content-Type: application/json
{
"meshUrl": "https://example.com/model.glb",
"operations": [
{ "type": "center", "options": {} },
{ "type": "scale", "options": { "factor": 1.5 } },
{ "type": "smooth", "options": { "iterations": 2 } },
{ "type": "decimate", "options": { "ratio": 0.5 } }
],
"outputFormat": "glb"
}
Available Operations:
| Operation | Description | Options |
|---|---|---|
center |
Center mesh at origin | - |
scale |
Scale mesh | factor: scale multiplier |
rotate |
Rotate mesh | x, y, z: rotation in degrees |
translate |
Move mesh | x, y, z: offset values |
smooth |
Smooth mesh surface | iterations: number of passes |
decimate |
Reduce polygon count | ratio: 0.0-1.0 |
triangulate |
Convert to triangles | - |
flip_normals |
Flip face normals | - |
recalc_normals |
Recalculate normals | angle: threshold angle |
remove_doubles |
Merge duplicate vertices | threshold: distance |
fill_holes |
Fill mesh holes | maxSize: max hole size |
Auto-Retopology#
Generate clean topology from a high-poly mesh.
POST /v1/3d/mesh/retopology
Authorization: Bearer <token>
Content-Type: application/json
{
"meshUrl": "https://example.com/sculpt.obj",
"targetPolyCount": 10000,
"preserveDetails": true,
"generateUVs": true,
"symmetry": "x"
}
Generate UVs#
Create UV mapping for a mesh.
POST /v1/3d/mesh/uv-unwrap
Authorization: Bearer <token>
Content-Type: application/json
{
"meshUrl": "https://example.com/model.glb",
"method": "smart_project",
"packMargin": 0.01,
"stretchMinimize": true
}
UV Methods:
| Method | Description |
|---|---|
smart_project |
Automatic projection-based unwrap |
cube_project |
Box projection |
cylinder_project |
Cylindrical projection |
sphere_project |
Spherical projection |
lightmap_pack |
Optimized for lightmaps |
Texture Generation#
Generate Textures#
Generate textures for an existing mesh.
POST /v1/3d/texture/generate
Authorization: Bearer <token>
Content-Type: application/json
{
"meshUrl": "https://example.com/model.glb",
"prompt": "Worn leather armor with metal studs, battle damage",
"style": "realistic",
"resolution": 2048,
"generatePBR": true,
"pbrMaps": ["diffuse", "normal", "roughness", "metallic", "ao"]
}
PBR Map Types:
| Map | Description |
|---|---|
diffuse |
Base color/albedo |
normal |
Normal map |
roughness |
Roughness map |
metallic |
Metallic map |
ao |
Ambient occlusion |
height |
Height/displacement map |
emissive |
Emission map |
Upscale Texture#
Increase texture resolution using AI.
POST /v1/3d/texture/upscale
Authorization: Bearer <token>
Content-Type: application/json
{
"textureUrl": "https://example.com/texture_1k.png",
"targetResolution": 4096,
"preserveDetails": true,
"denoising": 0.3
}
Auto-Rigging#
Rig Character#
Automatically rig a character mesh.
POST /v1/3d/rig/auto
Authorization: Bearer <token>
Content-Type: application/json
{
"meshUrl": "https://example.com/character.glb",
"rigType": "humanoid",
"options": {
"fingerBones": true,
"facialBones": true,
"ikSetup": true,
"skinWeights": "auto"
}
}
Rig Types:
| Type | Description |
|---|---|
humanoid |
Standard humanoid skeleton |
humanoid_simple |
Simplified humanoid |
quadruped |
Four-legged creature |
bird |
Bird/flying creature |
fish |
Aquatic creature |
insect |
Multi-legged insect |
custom |
Custom bone structure |
Retarget Animation#
Transfer animation from one rig to another.
POST /v1/3d/rig/retarget
Authorization: Bearer <token>
Content-Type: application/json
{
"sourceAnimation": "https://example.com/walk_cycle.fbx",
"targetRig": "https://example.com/character_rigged.glb",
"options": {
"preserveFootContact": true,
"adjustHips": true,
"boneMapping": "auto"
}
}
Animation Generation#
Generate Animation#
Create animation from text description.
POST /v1/3d/animation/generate
Authorization: Bearer <token>
Content-Type: application/json
{
"rigUrl": "https://example.com/character_rigged.glb",
"prompt": "Character performs a victory dance with fist pump",
"duration": 3.0,
"style": "exaggerated",
"looping": true,
"fps": 30
}
Animation Styles:
| Style | Description |
|---|---|
realistic |
Motion-captured quality |
stylized |
Stylized game animation |
exaggerated |
Cartoon exaggeration |
subtle |
Minimal, subtle motion |
Providers & Presets#
List Providers#
Get available AI providers and their capabilities.
GET /v1/3d/providers
Authorization: Bearer <token>
Response:
{
"success": true,
"data": [
{
"id": "hunyuan",
"name": "Hunyuan 3D",
"capabilities": ["text_to_3d", "image_to_3d", "texturing"],
"qualityTier": "high",
"averageTime": 120,
"costPerGeneration": 0.1,
"available": true
},
{
"id": "meshy",
"name": "Meshy AI",
"capabilities": ["text_to_3d", "image_to_3d", "texturing", "stylization"],
"qualityTier": "medium",
"averageTime": 60,
"costPerGeneration": 0.05,
"available": true
}
]
}
List Styles#
Get available generation styles.
GET /v1/3d/styles
Authorization: Bearer <token>
List Presets#
Get preconfigured generation presets.
GET /v1/3d/presets
Authorization: Bearer <token>
Response:
{
"success": true,
"data": [
{
"id": "game_character_high",
"name": "High-Quality Game Character",
"description": "Optimized for modern game engines",
"settings": {
"polyCount": "high",
"textureResolution": 4096,
"generateRig": true,
"rigType": "humanoid",
"format": "glb"
}
},
{
"id": "mobile_prop",
"name": "Mobile Game Prop",
"description": "Low-poly optimized for mobile",
"settings": {
"polyCount": "low",
"textureResolution": 512,
"format": "glb"
}
}
]
}
WebSocket Events#
Subscribe to real-time generation progress via WebSocket.
Subscribe to Job Updates#
{
"type": "subscribe",
"timestamp": "2024-01-15T10:00:00Z",
"channel": "job",
"resourceId": "job_3d_abc123",
"events": ["generation:progress", "generation:complete", "generation:failed"]
}
Event: generation:progress#
{
"type": "generation:progress",
"timestamp": "2024-01-15T10:00:30Z",
"jobId": "job_3d_abc123",
"jobType": "text_to_3d",
"progress": 45,
"stage": "generating_mesh",
"message": "Generating base mesh structure...",
"estimatedSecondsRemaining": 65
}
Event: generation:complete#
{
"type": "generation:complete",
"timestamp": "2024-01-15T10:01:35Z",
"jobId": "job_3d_abc123",
"jobType": "text_to_3d",
"resultUrl": "https://cdn.yemaya.io/3d/job_3d_abc123/model.glb",
"previewUrl": "https://cdn.yemaya.io/3d/job_3d_abc123/thumb.png",
"processingTime": 95000
}
Error Codes#
| Code | Description |
|---|---|
INVALID_PROMPT |
Prompt is empty or contains invalid content |
INVALID_IMAGE |
Image URL is invalid or inaccessible |
UNSUPPORTED_FORMAT |
Requested format not supported |
MESH_TOO_COMPLEX |
Input mesh exceeds complexity limits |
PROVIDER_UNAVAILABLE |
Selected AI provider is offline |
GENERATION_FAILED |
Generation process failed |
QUOTA_EXCEEDED |
Generation quota exceeded |
JOB_NOT_FOUND |
Job ID does not exist |
JOB_EXPIRED |
Job results have expired |
Rate Limits#
| Endpoint | Limit |
|---|---|
| Generation endpoints | 10/minute |
| Processing endpoints | 30/minute |
| Status/result endpoints | 100/minute |
Best Practices#
- Use Callbacks: For long-running generations, use
callbackUrlinstead of polling - Choose Appropriate Quality: Match
resolutionandpolyCountto your use case - Batch Similar Jobs: Group similar generations to optimize queue processing
- Cache Results: Store generated assets; regeneration is not guaranteed to produce identical results
- Handle Failures Gracefully: Implement retry logic with exponential backoff
SDK Examples#
TypeScript#
import { YemayaClient } from '@yemaya/sdk';
const client = new YemayaClient({ apiKey: 'yek_...' });
// Generate 3D model from text
const job = await client.generation3d.generateFromText({
prompt: 'A medieval castle with tall towers',
style: 'realistic',
format: 'glb',
generateTextures: true,
});
// Wait for completion
const result = await client.generation3d.waitForJob(job.jobId, {
onProgress: (progress) => console.log(`Progress: ${progress}%`),
});
console.log('Model URL:', result.model.url);
Python#
from yemaya import YemayaClient
client = YemayaClient(api_key="yek_...")
# Generate 3D model
job = client.generation_3d.generate_from_text(
prompt="A medieval castle with tall towers",
style="realistic",
format="glb"
)
# Wait for completion
result = client.generation_3d.wait_for_job(
job.job_id,
on_progress=lambda p: print(f"Progress: {p}%")
)
print(f"Model URL: {result.model.url}")