Moondraft — API Documentation

Getting Started

Authentication

All API requests require a Bearer token in the Authorization header.

Header

Authorization: Bearer md_your_api_key_here

To get an API key, create an account via the sign-up flow:

POST /v1/auth/send-code

Send a verification code to your email.

Param	Type	Description
emailrequired	string	Your email address

Send verification code

curl -X POST https://mdraftai-production.up.railway.app/v1/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'

POST /v1/auth/verify

Verify the code and receive your API key. You get 50 free credits on signup.

Param	Type	Description
emailrequired	string	Your email address
coderequired	string	6-digit code from your email

Verify and get API key

curl -X POST https://mdraftai-production.up.railway.app/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "code": "123456" }'

50 free credits on signup. No credit card required.

Base URL

https://mdraftai-production.up.railway.app

All endpoints are prefixed with /v1.

Image Generation

Generate Image

POST /v1/generate

Generate a single image from a text prompt. Optionally pass a style or character reference image.

Param	Type	Description
promptrequired	string	What to generate (max 4,000 chars)
quality	string	`standard` (default) or `premium`
aspect_ratio	string	Output ratio (default `16:9`). See table below.
style_ref	string	Base64 image to match the visual style of
character_ref	string	Base64 image of a character to keep consistent

Supported aspect ratios:

Ratio	Resolution
1:1	1024 x 1024
16:9	1344 x 768
9:16	768 x 1344
3:2	1216 x 832
2:3	832 x 1216
4:3	1152 x 896
3:4	896 x 1152

Response:

Response

{
  "success": true,
  "quality": "standard",
  "image": "data:image/png;base64,..."
}

Credits: 1 credit (standard) or 3 credits (premium) per image.

Generate an image

curl -X POST https://mdraftai-production.up.railway.app/v1/generate \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "product photo of sneakers on marble",
    "quality": "premium",
    "aspect_ratio": "1:1"
  }'

With style reference

curl -X POST https://mdraftai-production.up.railway.app/v1/generate \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "hero illustration for a fintech landing page",
    "style_ref": "data:image/png;base64,..."
  }'

Batch Generate

POST /v1/generate/batch

Generate up to 10 images in a single request. Same options as /v1/generate, but with an array of prompts.

Param	Type	Description
promptsrequired	string[]	Array of prompts (max 10)
quality	string	`standard` (default) or `premium`
aspect_ratio	string	Applied to all images
style_ref	string	Base64 style reference for all images
character_ref	string	Base64 character reference for all images

Response:

Response

{
  "results": [
    { "prompt": "hero shot", "image": "data:image/png;base64,...", "success": true },
    { "prompt": "side angle", "image": "data:image/png;base64,...", "success": true }
  ],
  "quality": "premium"
}

Credits: Per-image cost (1 or 3) multiplied by number of prompts.

Batch generate

curl -X POST https://mdraftai-production.up.railway.app/v1/generate/batch \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["hero shot", "side angle", "close-up detail"],
    "quality": "premium",
    "style_ref": "data:image/png;base64,..."
  }'

Edit Image

POST /v1/edit

Edit an existing image with a text prompt. Describe the changes you want.

Param	Type	Description
promptrequired	string	What to change
imagerequired	string	Base64-encoded source image

Response:

Response

{
  "success": true,
  "image": "data:image/png;base64,..."
}

Credits: 1 credit per edit.

Edit an image

curl -X POST https://mdraftai-production.up.railway.app/v1/edit \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "change the background to a beach sunset",
    "image": "data:image/png;base64,..."
  }'

Video Generation

Video

POST /v1/video

Generate a 5-second MP4 video. The endpoint uses smart routing based on what you send:

Input	Mode	What happens
prompt only	Text-to-video	Generates video from the description
prompt + image	Image-to-video	Animates the provided image
image + audio	Talking avatar	Lip-syncs the image to the audio

Param	Type	Description
prompt	string	Description or motion direction
image	string	Base64 image to animate
audio	string	Base64 audio for talking avatar

Credits: 10 credits per video. Output: 5-second MP4.

Text to video

curl -X POST https://mdraftai-production.up.railway.app/v1/video \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "slow pan across mountain lake, sunrise" }'

Animate an image

curl -X POST https://mdraftai-production.up.railway.app/v1/video \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "gentle push in with parallax",
    "image": "data:image/png;base64,..."
  }'

Talking avatar

curl -X POST https://mdraftai-production.up.railway.app/v1/video \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/png;base64,...",
    "audio": "data:audio/mp3;base64,..."
  }'

Enhancement

Enhance

POST /v1/enhance

Upscale an image to 2x resolution.

Param	Type	Description
imagerequired	string	Base64-encoded image to upscale

Response:

Response

{
  "success": true,
  "image": "data:image/png;base64,..."
}

Credits: 2 credits per enhancement.

Enhance an image

curl -X POST https://mdraftai-production.up.railway.app/v1/enhance \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{ "image": "data:image/png;base64,..." }'

Prompt

Prompt Refinement

POST /v1/prompt/refine

Automatically rewrite a rough prompt into a detailed, production-quality prompt optimized for generation.

Param	Type	Description
promptrequired	string	Your rough prompt
mode	string	`image` (default) or `video`

Response:

Response

{
  "refined_prompt": "A pair of white leather sneakers resting on a slab of Calacatta marble, soft directional lighting from upper left, shallow depth of field..."
}

Free -- no credits charged.

Refine a prompt

curl -X POST https://mdraftai-production.up.railway.app/v1/prompt/refine \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "sneakers on marble", "mode": "image" }'

Credits

Check Balance

GET /v1/credits

Returns your current credit balance.

Check balance

curl https://mdraftai-production.up.railway.app/v1/credits \
  -H "Authorization: Bearer md_..."

Usage History

GET /v1/usage

Returns your last 100 actions with timestamps, types, and credit costs.

Get usage history

curl https://mdraftai-production.up.railway.app/v1/usage \
  -H "Authorization: Bearer md_..."

Buy Credits

POST /v1/credits/buy

Purchase a credit pack. Returns a Stripe checkout URL.

Param	Type	Description
packrequired	string	`pack_100`, `pack_300`, or `pack_1000`

Response:

Response

{
  "checkout_url": "https://checkout.stripe.com/..."
}

Buy credits

curl -X POST https://mdraftai-production.up.railway.app/v1/credits/buy \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{ "pack": "pack_300" }'

Auto-Reload

Set a threshold so your credits automatically replenish when they run low. Your app never stops generating.

POST /v1/credits/auto-reload

Enable or update auto-reload settings.

Param	Type	Description
thresholdrequired	number	Reload when balance drops below this
packrequired	string	`pack_100`, `pack_300`, or `pack_1000`

Enable auto-reload

curl -X POST https://mdraftai-production.up.railway.app/v1/credits/auto-reload \
  -H "Authorization: Bearer md_..." \
  -H "Content-Type: application/json" \
  -d '{ "threshold": 50, "pack": "pack_1000" }'

GET /v1/credits/auto-reload

Check current auto-reload settings.

Get auto-reload settings

curl https://mdraftai-production.up.railway.app/v1/credits/auto-reload \
  -H "Authorization: Bearer md_..."

DELETE /v1/credits/auto-reload

Disable auto-reload.

Disable auto-reload

curl -X DELETE https://mdraftai-production.up.railway.app/v1/credits/auto-reload \
  -H "Authorization: Bearer md_..."

Reference

Rate Limits

Per-minute limits per API key. Exceeding these returns 429 Too Many Requests.

Endpoint	Method	Limit
/v1/generate	POST	10 req/min
/v1/generate/batch	POST	3 req/min
/v1/edit	POST	10 req/min
/v1/video	POST	5 req/min
/v1/enhance	POST	10 req/min
/v1/prompt/refine	POST	20 req/min
/v1/credits	GET	30 req/min
/v1/usage	GET	10 req/min
/v1/credits/buy	POST	5 req/min
/v1/credits/auto-reload	POST/GET/DELETE	10 req/min
/v1/auth/send-code	POST	3 req/min
/v1/auth/verify	POST	5 req/min

Error Handling

All errors return JSON with an error string.

Error response format

{
  "error": "Insufficient credits. You need 3 credits but have 1."
}

HTTP status codes:

Code		Meaning
400		Bad request -- missing or invalid parameters
401		Unauthorized -- invalid or missing API key
402		Insufficient credits
404		Endpoint not found
410		Content policy violation -- prompt was rejected
413		Payload too large -- image exceeds 10 MB or body exceeds 50 MB
429		Rate limit exceeded -- slow down
500		Internal server error
503		Service temporarily unavailable

Common errors:

Error		What to do
Content policy	410	Rephrase your prompt. The content was flagged.
Insufficient credits	402	Buy more credits or enable auto-reload.
Generation failed	500	Retry. Credits are auto-refunded on failure.
Timed out	503	Retry after a few seconds. Credits are refunded.

Credits are automatically refunded when a generation fails or times out.

Input Limits

Limit		Value
Max prompt length		4,000 characters
Max image size		10 MB (base64-encoded)
Max batch size		10 prompts
Max request body		50 MB

MCP Integration

POST /mcp

Moondraft exposes all generation tools via the Model Context Protocol. This means you can generate images and video directly from Claude Code, Cursor, Windsurf, or any MCP-compatible client.

Add this to your ~/.mcp.json:

~/.mcp.json

{
  "mcpServers": {
    "moondraft": {
      "type": "url",
      "url": "https://mdraftai-production.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Once configured, your AI coding assistant can generate images, create videos, enhance assets, and manage credits -- all from natural language in your terminal or editor.

Example usage in Claude Code

# In your terminal, just ask:
"Generate a hero illustration for the landing page and save it to assets/"
"Create 5 onboarding illustrations matching the app's color scheme"
"Animate this product photo with a slow zoom"