{
  "openapi": "3.1.0",
  "info": {
    "title": "Zapmatte Green Screen Removal API",
    "version": "1.0.0",
    "summary": "Remove a green or blue screen from a video and get ProRes 4444, transparent WebM, an alpha matte or an MP4 on a solid colour.",
    "description": "Upload a clip shot in front of a green, blue or teal screen and get the subject back with transparency. Jobs spend the same credits as the website (1 credit = 1 second at Standard, 2 at Fine edges), follow the same content rules, and failed jobs are refunded automatically. Authenticate with a personal key created at https://zapmatte.com/developers (Authorization: Bearer zap_mcp_...). Guide: https://zapmatte.com/developers",
    "contact": { "name": "Zapmatte support", "url": "https://zapmatte.com/support", "email": "support@zapmatte.com" },
    "termsOfService": "https://zapmatte.com/terms"
  },
  "externalDocs": { "description": "Developer guide", "url": "https://zapmatte.com/developers" },
  "servers": [{ "url": "https://zapmatte.com" }],
  "security": [{ "bearerKey": [] }],
  "tags": [
    { "name": "Account", "description": "Credit balance" },
    { "name": "Upload", "description": "Screen a clip and get a one-time upload URL" },
    { "name": "Jobs", "description": "Start a removal and follow it" }
  ],
  "paths": {
    "/api/me/credits": {
      "get": {
        "tags": ["Account"],
        "operationId": "getCredits",
        "summary": "Get your credit balance",
        "responses": {
          "200": {
            "description": "Balance",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/upload/video": {
      "post": {
        "tags": ["Upload"],
        "operationId": "createUpload",
        "summary": "Screen a clip and get a one-time upload URL",
        "description": "Send the clip's metadata and 1-4 JPEG frames sampled across it. The frames are checked for content (requests are refused if checking is unavailable). On success, PUT the video bytes to putUrl with the returned contentType, then pass key as uploadKey when you start the job. The video itself never passes through this endpoint. Request body limit with a key: 2 MB.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Upload slot",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "description": "Content checking unavailable; try again in a minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/generate": {
      "post": {
        "tags": ["Jobs"],
        "operationId": "removeGreenScreen",
        "summary": "Start a green screen removal (spends credits)",
        "description": "Starts a paid job on an uploaded clip. expectedCredits must equal the exact cost (billable seconds = duration rounded up, 1-180; cost = seconds x 1 for standard, x 2 for fine). requestId deduplicates identical retries for 24 hours: retry an uncertain submission with the same requestId, never a new one. Request body limit with a key: 16 KB.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Job started",
            "headers": { "Idempotency-Replayed": { "description": "true when this is the stored answer to an earlier identical request", "schema": { "type": "string" } } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalStarted" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": {
            "description": "Not enough credits (nothing was charged)",
            "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "required": { "type": "integer" } } }] } } }
          },
          "409": { "description": "idempotency_conflict (same requestId, different parameters) or submission_pending (outcome unknown; check https://zapmatte.com/dashboard/history)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "description": "record_failed: the job could not be recorded and credits were refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "provider_failed: the job failed to start and credits were refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Temporarily unavailable (busy balance update or request protection); retry with the same requestId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/generate/status": {
      "get": {
        "tags": ["Jobs"],
        "operationId": "getRemovalStatus",
        "summary": "Check a job",
        "description": "Poll no faster than every 5 seconds. On success, outputs holds public URLs of the files. Failed jobs are refunded automatically.",
        "parameters": [{ "name": "taskId", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Job state",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalStatus" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "description": "No such job in your account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "description": "status_failed: checking failed this time; poll again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/download": {
      "get": {
        "tags": ["Jobs"],
        "operationId": "downloadOutput",
        "summary": "Download one output as a file",
        "description": "Redirects (302) to a short-lived download URL with Content-Disposition: attachment. No key needed: anyone with the task id can download, like the shareable result page.",
        "security": [],
        "parameters": [
          { "name": "task", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "file", "in": "query", "required": true, "schema": { "type": "string", "enum": ["mov", "webm", "matte", "mp4", "preview"] } }
        ],
        "responses": {
          "302": { "description": "Redirect to the file" },
          "404": { "description": "Not found or not finished" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": { "type": "http", "scheme": "bearer", "description": "Personal key (zap_mcp_...), valid 30 days, up to 5 per account. Create and revoke at https://zapmatte.com/developers." }
    },
    "responses": {
      "BadRequest": { "description": "Invalid input (see code)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing, invalid or expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "TooLarge": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": {
        "description": "Another request for this account is running, or too many requests. Wait and retry.",
        "headers": { "Retry-After": { "schema": { "type": "integer" } } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "const": false },
          "error": { "type": "string", "description": "Human-readable message" },
          "code": { "type": "string", "examples": ["auth_required", "invalid_arguments", "unsupported_type", "file_too_large", "too_long", "too_big_frame", "unreadable", "video_blocked", "moderation_unavailable", "invalid_upload", "upload_incomplete", "invalid_duration", "invalid_mode", "invalid_background", "insufficient_credits", "free_queue", "rate_limited", "body_too_large", "idempotency_conflict", "submission_pending", "busy", "provider_failed", "record_failed", "status_failed", "request_unavailable"] }
        }
      },
      "Credits": {
        "type": "object",
        "properties": {
          "ok": { "const": true },
          "balance": { "type": "integer", "description": "Spendable credits" },
          "monthly": { "type": "integer" },
          "topup": { "type": "integer" },
          "plan": { "type": "string" },
          "hasEverPaid": { "type": "boolean" }
        }
      },
      "UploadRequest": {
        "type": "object",
        "required": ["name", "size", "duration", "frames"],
        "properties": {
          "name": { "type": "string", "description": "File name; the extension sets the format (mp4, mov, m4v, webm, mkv)", "examples": ["intro.mp4"] },
          "type": { "type": "string", "description": "MIME type", "examples": ["video/mp4"] },
          "size": { "type": "integer", "maximum": 524288000, "description": "Bytes (up to 500 MB)" },
          "duration": { "type": "number", "maximum": 180.5, "description": "Seconds (up to 3 minutes)" },
          "width": { "type": "integer", "description": "Up to 4K (3840x2160 or 4096 wide)" },
          "height": { "type": "integer" },
          "frames": {
            "type": "array", "minItems": 1, "maxItems": 4,
            "items": { "type": "string", "pattern": "^data:image/jpeg;base64,", "description": "JPEG data URL, up to 600 KB each" }
          }
        }
      },
      "UploadResponse": {
        "type": "object",
        "properties": {
          "ok": { "const": true },
          "key": { "type": "string", "description": "Pass as uploadKey", "examples": ["up/2026-11-22/e2025775-8170-4536-9332-dd8bd55434b7.mp4"] },
          "putUrl": { "type": "string", "format": "uri", "description": "One-time URL: PUT the video bytes here" },
          "url": { "type": "string", "format": "uri" },
          "contentType": { "type": "string", "description": "Send this as the Content-Type of the PUT" }
        }
      },
      "RemovalRequest": {
        "type": "object",
        "required": ["requestId", "uploadKey", "mode", "durationSeconds", "expectedCredits"],
        "properties": {
          "requestId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{16,80}$", "description": "Unique id, e.g. a UUID" },
          "uploadKey": { "type": "string" },
          "mode": { "type": "string", "enum": ["standard", "fine"], "description": "standard = 1 credit/s (green, blue and teal screens); fine = 2 credits/s, finer hair, 30 fps output" },
          "durationSeconds": { "type": "number", "maximum": 180.5 },
          "expectedCredits": { "type": "integer", "description": "Exact cost; the request fails if it doesn't match" },
          "background": {
            "type": "object",
            "default": { "type": "transparent" },
            "required": ["type"],
            "properties": {
              "type": { "type": "string", "enum": ["transparent", "color"] },
              "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Required when type is color; adds an MP4 output" }
            }
          }
        }
      },
      "RemovalStarted": {
        "type": "object",
        "properties": {
          "ok": { "const": true },
          "taskId": { "type": "string" },
          "mode": { "type": "string" },
          "seconds": { "type": "integer", "description": "Billable seconds" },
          "creditsCharged": { "type": "integer" },
          "newBalance": { "type": "integer" },
          "free": { "type": "boolean", "description": "Account has never paid: the result is shown no sooner than minWaitMs after submit" },
          "minWaitMs": { "type": "integer" }
        }
      },
      "RemovalStatus": {
        "type": "object",
        "properties": {
          "ok": { "const": true },
          "state": { "type": "string", "enum": ["queued", "generating", "success", "fail"] },
          "progress": { "type": "number", "minimum": 0, "maximum": 1 },
          "seconds": { "type": "integer" },
          "outputs": {
            "type": "object",
            "description": "Public URLs, on success",
            "properties": {
              "mov": { "type": "string", "format": "uri", "description": "ProRes 4444 MOV with alpha" },
              "webm": { "type": "string", "format": "uri", "description": "VP9 WebM with alpha" },
              "matte": { "type": "string", "format": "uri", "description": "Black-and-white alpha matte MP4" },
              "mp4": { "type": "string", "format": "uri", "description": "MP4 on the chosen colour (colour backgrounds only)" },
              "preview": { "type": "string", "format": "uri" }
            }
          },
          "free": { "type": "boolean", "description": "Account has never paid and the result is held until a minute after submit" },
          "readyInMs": { "type": "integer", "description": "With free: how long until the result is shown" },
          "refunded": { "type": "boolean", "description": "On fail: credits were returned" },
          "error": { "type": "string" }
        }
      }
    }
  }
}
