API reference

A JSON REST API over HTTPS. One error shape, one job envelope, and a stable error.code on everything that can go wrong.

Base URL: https://gateway.market4me.ai//api/v1v1.0.0

Authentication

Every request needs an API key. Create one in the dashboard under Settings → API & integrations. The key is shown once — we store only a SHA-256 hash and genuinely cannot recover it, so if you lose it, revoke it and make another.

# preferred
curl https://gateway.market4me.ai//api/v1/me -H "Authorization: Bearer m4m_live_..."

# equivalent, for clients that only support an API-key header
curl https://gateway.market4me.ai//api/v1/me -H "X-API-Key: m4m_live_..."

Keys are prefixed m4m_live_ or m4m_test_. A key inherits exactly the access of the person who created it — the same workspace, the same role — and can never exceed it.

Scopes

A key created with no scopes has full access — the common case. Selecting scopes makes it a strict allow-list, which is what you want for a key you hand to a third party or an agent.

GET /v1/scopes tells you which scopes the calling key actually holds.

Errors

Every failure returns the same shape. Branch on error.code — it is stable. error.message is written to be read by a person or a model and says what to do next, but it is not a contract.

{
  "error": {
    "type": "insufficient_credits_error",
    "code": "insufficient_credits",
    "message": "This operation costs 350 credits but the account has 120. Top up at …/dashboard/billing.",
    "credits_required": 350,
    "credits_available": 120,
    "request_id": "req_8f21c0…",
    "doc_url": "https://market4me.ai/docs/api#insufficient_credits"
  }
}

Codes worth handling explicitly

Every response carries an X-Request-Id header, echoed as error.request_id. Quote it in support requests.

Rate limits

Limits are per key, per minute — not per IP, so your server-to-server integration is not throttled by traffic from elsewhere in your company. The default is 120 requests/minute and you can set it per key when you create it.

Rate limits are about fairness, not billing. Credits are the billing control, and a rate limit never charges you.

Idempotency

Send an Idempotency-Key header on any POST. Replaying the same key returns the original response instead of doing the work again — so a timeout, a retry or a duplicated queue message cannot charge you twice.

curl https://gateway.market4me.ai//api/v1/videos \
  -H "Authorization: Bearer m4m_live_..." \
  -H "Idempotency-Key: 7f3c1e90-2b44-4a1e-9d77-8c0e2a1b5f60" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a neon sign flickering on at dusk"}'

• Use a fresh UUID per logical operation, and reuse it across retries of that operation.
• A replayed response carries Idempotent-Replay: true.
• Same key with a different body is a 409 — that is a bug on the caller's side, and answering with the wrong cached response would be worse than failing.
• Keys are remembered for 24 hours, and are scoped to the API key that used them.
• Only successful responses are cached. A failure can always be retried with the same key.

Jobs

Short generations (clips, images, speech, avatars) return the finished asset directly. Long ones — /brand-videos, /films — return a job, and every job in the API looks the same regardless of which engine is doing the work.

{
  "id": "job_9f2c1a7e4b…",
  "object": "job",
  "kind": "brand_video",
  "status": "running",          // queued → running → succeeded | failed | cancelled
  "progress": 45,
  "credits": 120,
  "output": null,               // populated once succeeded
  "error": null,                // why it failed; credits are refunded automatically
  "metadata": { "your": "data" },
  "poll_url": "https://gateway.market4me.ai//api/v1/jobs/job_9f2c1a7e4b…",
  "is_terminal": false,
  "created_at": "2026-07-21T10:04:11Z",
  "completed_at": null
}

On success, output.url is the finished asset — a stable, shareable link you can hand straight to a user. output.download_url is a direct download that expires after 24 hours.

Waiting for a job

Three ways, best first:

1. Webhooks — be told. Best for a real integration. See below.
2. POST /jobs/{id}/wait — one blocking call that returns as soon as the job is terminal (up to timeout_s, max 300). Ideal for scripts and AI agents, which have no reliable timer of their own.
3. Polling GET /jobs/{id} — works, but you are writing a loop that the other two make unnecessary.

# blocks until finished, or returns timed_out:true so you can call again
curl -X POST https://gateway.market4me.ai//api/v1/jobs/job_9f2c1a7e4b/wait \
  -H "Authorization: Bearer m4m_live_..." \
  -H "Content-Type: application/json" \
  -d '{"timeout_s": 120}'

Webhooks

Register an endpoint and Market4Me POSTs to it when a job finishes, instead of you polling.

curl https://gateway.market4me.ai//api/v1/webhooks \
  -H "Authorization: Bearer m4m_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yourapp.com/hooks/market4me","events":["job.succeeded","job.failed"]}'

The response contains a secret — shown once. Store it; you need it to verify deliveries.

Events

Omit events to receive everything.

Verifying a delivery

Each request carries M4M-Signature: t=<unix>,v1=<hex>, where the digest is HMAC-SHA256 over {timestamp}.{raw body}. Check the digest and the age — the timestamp is inside the signed payload precisely so a captured request cannot be replayed later.

import crypto from 'node:crypto'

// IMPORTANT: verify against the RAW body, before any JSON parsing.
export function verify(rawBody, header, secret) {
  const t  = /t=(\d+)/.exec(header)?.[1]
  const v1 = /v1=([a-f0-9]+)/.exec(header)?.[1]
  if (!t || !v1) return false

  // Reject anything older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false

  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.${rawBody}`).digest('hex')

  // Constant-time compare — a plain === leaks the digest byte by byte.
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

import hmac, hashlib, time, re

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    t  = re.search(r"t=(\d+)", header)
    v1 = re.search(r"v1=([a-f0-9]+)", header)
    if not t or not v1:
        return False
    if abs(time.time() - int(t.group(1))) > 300:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{t.group(1)}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(v1.group(1), expected)

Delivery behaviour

• Answer 2xx within 10 seconds. Do the real work asynchronously.
• Failures retry 6 times with backoff over roughly 2 hours.
• An endpoint that fails 20 times consecutively is disabled — check GET /webhooks if deliveries stop.
• Redirects are not followed. Register the final URL.
• Endpoints must be public https. Private, loopback and link-local addresses are rejected, and re-checked before every delivery.
• POST /webhooks/{id}/test sends a test event so you can verify your endpoint without spending credits on a real render.

Models

Generation endpoints take an optional model, expressed as a quality/price tier. Omit it and you get a sensible default — most callers should.

Images use economy, standard and premium. GET /v1/models returns the live catalogue with per-tier prices, so you can pick on cost rather than guessing.

All endpoints

Generated from the OpenAPI spec this API actually serves, so it cannot drift from the implementation.

Driving this from an AI agent instead? The MCP server wraps all of this as tools for Claude, ChatGPT and Cursor.