Getting Started
INTRODUCTION
AUTHENTICATION
SDKS
Endpoints
POST /GENERATE
GET /JOBS
GET /VAULT
POST /SPEECH
POST /MUSIC
Reference
ERROR CODES
RATE LIMITS
WEBHOOKS
REST API · VERSION 2.0
MercaDream API.
Programmatic access to the full MercaDream generation stack. Generate cinematic video, synthesize speech, compose music, and manage your Vault all through a clean REST interface.
INTRODUCTION
Base URL for all API requests:
https://api.mercadream.com/v2
All requests must be made over HTTPS. The API accepts JSON request bodies and returns JSON responses. Timestamps are in ISO 8601 format (UTC).
NOTE
API access requires a Regular, Professional, or Advanced plan. Free plan does not include API access.
AUTHENTICATION
All API requests require authentication via Bearer token. Include your API key in the Authorization header.
LIVE KEY
mk_live_x9pq7
TEST KEY
mk_test_k3j8
EXAMPLE REQUEST
curl -X POST https://api.mercadream.com/v2/generate \
-H "Authorization: Bearer mk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"prompt": "Neon rain on Tokyo streets", "resolution": "4k"}'
SDKs & LIBRARIES
Official client libraries for the most common languages. Community SDKs available on GitHub.
PYTHON
JAVASCRIPT
RUST
GO
# Install
pip install mercadream
# Initialize
from mercadream import MercaClient
client = MercaClient("mk_live_your_key")
# Generate video
job = client.generate(
prompt="Neon rain on Tokyo streets at midnight",
resolution="4k",
duration=30,
style="cinematic"
)
# Wait for completion
result = client.jobs.wait(job.id)
print(result.download_url)
POST /GENERATE
Submit a new generation job. Returns a job object with status tracking.
POST
/v2/generate
Create generation job
?
REQUEST BODY
| PARAMETER | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| prompt | string | required | Cinematic description (max 1000 chars) |
| resolution | string | optional | "720p" | "1080p" | "4k" | "8k" default: "4k" |
| duration | integer | optional | Seconds: 15 | 30 | 60 | 120 default: 30 |
| style | string | optional | Visual style preset default: "cinematic" |
| fps | integer | optional | 24 | 30 | 60 default: 24 |
| voice_id | string | optional | Voice model ID for narration |
| webhook_url | string | optional | URL to receive completion event |
EXAMPLE RESPONSE
{
"id": "job_01j8x9k2m4p6q8r",
"status": "queued",
"prompt": "Neon rain on Tokyo streets at midnight",
"resolution": "4k",
"duration": 30,
"compute_units": 12,
"created_at": "2025-06-01T14:22:31Z",
"estimated_completion": "2025-06-01T14:23:16Z"
}
GET /JOBS
Retrieve job status and download URLs upon completion.
GET
/v2/jobs/{job_id}
Get job status
?
EXAMPLE RESPONSE (COMPLETED)
{
"id": "job_01j8x9k2m4p6q8r",
"status": "completed",
"progress": 100,
"download_url": "https://vault.mercadream.com/...",
"thumbnail_url": "https://vault.mercadream.com/...",
"duration": 30,
"resolution": "4k",
"file_size_bytes": 284772400,
"completed_at": "2025-06-01T14:23:14Z"
}
GET
/v2/jobs
List all jobs
?
QUERY PARAMETERS
| status | string | optional | Filter: "queued" | "processing" | "completed" | "failed" |
| limit | integer | optional | Max results (1100, default: 20) |
| before | string | optional | ISO 8601 cursor for pagination |
POST /SPEECH
Generate neural speech with voice cloning or preset voices.
POST
/v2/speech
Synthesize speech
?
| text | string | required | Text to synthesize (max 5000 chars) |
| voice_id | string | optional | Voice model ID default: "neural-narrator-m" |
| format | string | optional | "mp3" | "wav" | "flac" default: "mp3" |
| speed | float | optional | 0.52.0 default: 1.0 |
POST /MUSIC
Generate original music scores from text descriptions.
POST
/v2/music
Compose music
?
| prompt | string | required | Music description (genre, mood, instruments) |
| duration | integer | optional | Seconds: 15300 default: 60 |
| format | string | optional | "mp3" | "wav" | "flac" default: "mp3" |
| bpm | integer | optional | 60200 auto-detected if omitted |
ERROR CODES
All errors follow a consistent JSON structure with a code and human-readable message.
200
OK Request successful
201
Created Job successfully submitted
400
Bad Request Invalid parameters or malformed JSON
401
Unauthorized Missing or invalid API key
403
Forbidden Feature not available on your plan
404
Not Found Job or resource does not exist
429
Too Many Requests Rate limit exceeded
500
Internal Server Error Please contact support
RATE LIMITS
Rate limits are applied per API key per minute.
| PLAN | REQUESTS / MIN | CONCURRENT JOBS | MAX RESOLUTION |
|---|---|---|---|
| Regular | 60 | 2 | 720p |
| Advanced | 200 | 5 | 4K |
| Professional | 1,000 | 20 | 8K |
WEBHOOKS
Receive real-time notifications when your jobs complete, fail, or update.
Include a webhook_url in your generation request. MercaDream will POST a signed payload to that URL upon status change.
WEBHOOK PAYLOAD
{
"event": "job.completed",
"job_id": "job_01j8x9k2m4p6q8r",
"status": "completed",
"download_url": "https://vault.mercadream.com/...",
"timestamp": "2025-06-01T14:23:14Z",
"signature": "sha256=abc123..."
}