API Reference

Complete reference for the Model Store REST API. Authentication, endpoints, webhooks, and error handling.

Base URLhttps://api.model.store/v1

Authentication

X-API-Key Header

All API requests require authentication via the X-API-Key header. Keys are scoped to workspaces and can be managed in the dashboard.

http

X-API-Key: msk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Key Types

Prefix	Environment	Description
`msk_live_`	Production	Live API access, billable usage
`msk_test_`	Sandbox	Testing, mock responses, no billing

Security

Store keys in environment variables. Never commit to version control.

POST

/v1/generate/{modelSlug}

Submit a generation job. Returns immediately with job ID; results delivered via webhook.

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Text prompt for generation
`image_upload`	string	No	Base64 or URL of input image
`resolution`	string	No	Output size (e.g. 1024x1024)
`webhook_url`	string	Yes	URL for result delivery

Example

bash

curl -X POST "https://api.model.store/v1/generate/flux-pro" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at golden hour",
    "resolution": "1024x1024",
    "webhook_url": "https://your-app.com/webhook"
  }'

Response

json

{
  "id": "gen_a1b2c3d4e5f6",
  "status": "queued",
  "model": "flux-pro",
  "created_at": "2024-01-15T10:30:00.000Z",
  "estimated_time": 12
}

GET

/v1/jobs/{jobId}

Poll for job status and results. Alternative to webhooks for simple integrations.

json

{
  "id": "gen_a1b2c3d4e5f6",
  "status": "completed",
  "outputs": [{
    "url": "https://cdn.model.store/outputs/gen_.../0.png",
    "type": "image/png",
    "width": 1024,
    "height": 1024
  }],
  "metadata": {
    "prompt": "A serene mountain landscape...",
    "seed": 42,
    "inference_time_ms": 11234
  }
}

Webhooks

Receiving Results

Webhooks deliver results asynchronously to your specified endpoint. Your endpoint must respond with 2xx within 30 seconds.

Webhook Payload

json

{
  "id": "gen_a1b2c3d4e5f6",
  "event": "job.completed",
  "status": "completed",
  "outputs": [{
    "url": "https://cdn.model.store/outputs/...",
    "type": "image/png"
  }],
  "metadata": {
    "prompt": "...",
    "inference_time_ms": 11234
  }
}

Signature Verification

Verify webhook authenticity using the signature header:

javascript

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  
  return signature === `sha256=${expected}`;
}

We retry failed deliveries with exponential backoff up to 3 times.

Reference

Common Error Codes

HTTP	Code	Description
400	`INVALID_REQUEST`	Malformed request or missing fields
401	`INVALID_API_KEY`	API key missing, invalid, or revoked
402	`INSUFFICIENT_CREDITS`	Account balance depleted
404	`MODEL_NOT_FOUND`	Model slug doesn't exist
422	`CONTENT_FILTERED`	Output blocked by safety
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error, retry with backoff

Limits

Rate Limits

Tier	Requests/min	Concurrent Jobs
Free	10	2
Pro	100	20
Enterprise	Custom	Custom

View available models →