API Reference
Complete reference for the Myrlin API endpoints.
Authentication
All API requests require authentication via an API key passed in the X-API-Key header.
curl https://api.myrlin.io/v1/generate \
-H "X-API-Key: myrl_your_key_here"Create API keys in your Settings page.
/v1/generateStart a new 3D asset generation. Each generation costs 7 tokens (~$0.70).
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| prompt | string | Required | Text description of the asset to generate |
| workflow | string | Optional | "text_to_3d" (default) or "image_to_3d" |
| style | string | Optional | Style preset. Default: "hytale" |
| output_format | string | Optional | "glb", "blockymodel", or "both" (default) |
| reference_image_base64 | string | Optional | Base64 encoded image for image_to_3d workflow |
| voxel_size | number | Optional | Voxel resolution: 0.1 (32px classic), 0.067 (48px default), 0.05 (64px HD) |
| api_version | int | Optional | Set to 2 to enable v2 features like target_size. Default: 1 |
| target_size | object | Optional | V2 only. Target dimensions in Hytale units. {"x": 65} for uniform scale, or {"x": 65, "y": 12, "z": 3} for per-axis. Max 512 per axis. |
Example Request
{
"prompt": "A steampunk pistol with brass gears and copper pipes",
"workflow": "text_to_3d",
"style": "hytale",
"output_format": "both"
}V2 Example: Target Dimensions
Set api_version to 2 and provide target_size to control the output model dimensions in Hytale units. The model is rescaled after voxelization to match your target. Omitting target_size preserves default behavior.
{
"prompt": "A Persian scimitar sword for Hytale",
"style": "hytale",
"api_version": 2,
"target_size": {"x": 65}
}Response
{
"id": "gen_abc123def456",
"status": "pending",
"progress": 0,
"glb_url": null,
"blockymodel_url": null,
"texture_url": null,
"tokens_charged": 7,
"created_at": "2024-01-15T10:30:00Z"
}/v1/generations/:idGet the status and results of a generation. Poll this endpoint until status is "complete" or "failed".
Response
{
"id": "gen_abc123def456",
"status": "complete",
"progress": 100,
"glb_url": "https://storage.myrlin.ai/...",
"blockymodel_url": "https://storage.myrlin.ai/...",
"texture_url": "https://storage.myrlin.ai/...",
"tokens_charged": 7,
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:32:15Z"
}Status Values
pendingGeneration queued, waiting to startgeneratingGeneration in progresscompleteGeneration finished, URLs availablefailedGeneration failed, check error field/v1/balanceGet your current token balance and account information.
Response
{
"balance": 150,
"lifetime_purchased": 500,
"lifetime_spent": 350,
"lifetime_bonus": 0
}/v1/usageGet your API usage history for the current API key.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | Optional | Number of records to return (default: 50, max: 100) |
| hours | integer | Optional | Filter to last N hours (default: 24) |
Response
{
"usage": [
{
"id": "usg_123",
"endpoint": "/v1/generate",
"workflow_mode": "text_to_3d",
"tokens_charged": 7,
"success": true,
"created_at": "2024-01-15T10:30:00Z"
}
],
"stats": {
"total_requests": 47,
"successful_requests": 45,
"failed_requests": 2,
"total_tokens": 235,
"avg_response_time_ms": 125000
}
}Error Codes
Error Response Format
{
"detail": "Insufficient token balance. Need 7 tokens, have 2."
}Rate Limits
API requests are rate limited per API key to ensure fair usage.
| Window | Limit |
|---|---|
| Per Minute | 10 requests |
| Per Hour | 100 requests |
| Per Day | 1,000 requests |
Rate Limit Exceeded
When you exceed a rate limit, you'll receive a 429 response with a Retry-After header indicating how many seconds to wait.