# Machine Vision Cloud

> Vision inference API for software developers and their coding agents: define a
> visual task in natural language, POST an image, get structured JSON back
> (verdicts, bounding boxes, classes, text, polygon segments). Accuracy is tuned
> with curated reference images ("visual context"), not retraining. Capabilities
> beyond chat-model APIs (e.g. text-prompted instance segmentation) are routed to
> specialized models behind the same contract.

Base URL: https://api.machinevision.cloud
Auth: `Authorization: Bearer <mvc_live_... or mvc_test_...>` (create keys in the
console at https://machinevision.cloud). `mvc_test_` sandbox keys are free forever
and return deterministic mock results with the exact production schema — build and
test your integration end-to-end before spending anything. Free tier: 300 live
inspections/month, no card required.

## Quickstart

1. Create a task (one natural-language instruction defines the model's job):
   POST /tasks
   {"name": "damage_check", "task_type": "visual_inspection",
    "instruction": "Inspect the returned item for scratches, dents, or cracks."}
2. Run it:
   POST /tasks/{task_id}/inspect
   {"image_url": "https://example.com/photo.jpg"}
   -> {"result": {"verdict": "FAIL", "defects": [{"class": "scratch",
      "bounding_box": {...}, "confidence": 0.93, ...}]}, "usage": {...}}
3. Improve accuracy: create a visual context (POST /contexts), add labeled
   reference images (POST /contexts/{id}/items), and point the task at it
   (PATCH /tasks/{id} inference_config.context_id). No training pipeline.

Task types: visual_inspection, anomaly_detection, object_detection, segmentation,
classification, ocr, visual_qa, plus experimental pose_estimation and measurement.
Send `Idempotency-Key` headers on inspections to make retries safe. Errors use
{"error": {"code", "message"}} with stable codes.

## Key endpoints

- [OpenAPI document](https://api.machinevision.cloud/openapi.json): the complete,
  generated contract - request/response schemas for every endpoint
- POST /tasks, GET /tasks, PATCH /tasks/{id}: define and manage tasks
- POST /tasks/{id}/inspect: run one image (JSON image_url or multipart upload)
- POST /tasks/{id}/batch: run up to 1000 images asynchronously
- GET /templates, POST /templates/{id}/tasks: ready-made task gallery
- POST /contexts, POST /contexts/{id}/items: visual context curation
- GET /usage: monthly usage, spend, and remaining free tier
- GET /health: liveness

## MCP

Remote MCP server (streamable HTTP, stateless): https://api.machinevision.cloud/mcp
Authenticate with the same Bearer API key. Tools: list_templates,
create_task_from_template, create_task, list_tasks, get_task, inspect_image,
list_contexts, add_context_item, get_usage.

## Docs

- [Console & quickstart](https://machinevision.cloud/docs)
- [API reference](https://machinevision.cloud/docs/api)