Name: visionaix GeoCalib Single-Image Camera Calibration API
Brand: magicapi
SKU: api-magicapi-single-image-camera-calibration-visionaix-geocalib
Availability: InStock
Author: API Market

Shashank Agarwal

# 📷 Single-Image Camera Calibration API (visionaix GeoCalib)

## Overview
GeoCalib is a camera calibration model from the ECCV 2024 paper "Single-Image Camera Calibration with Geometric Optimization". Its developer describes it as estimating focal length, field of view, lens distortion, roll and pitch from one image, using a neural network followed by a Levenberg-Marquardt optimizer, on both indoor and outdoor scenes.

Send one image URL. Each request returns a calibration JSON document (camera intrinsics, gravity direction and uncertainty estimates) and, by default, a visualization image of the predicted geometric fields.

## Features
- **Camera intrinsics from one photo**: focal length in pixels (x and y), principal point, vertical and horizontal field of view, and the 3x3 intrinsic matrix `K`.
- **Gravity direction**: roll and pitch in degrees and radians, a 3D gravity vector and a rotation matrix `R`.
- **Uncertainty estimates**: roll, pitch, focal length, vertical field of view and gravity uncertainty for each result.
- **Four camera models**: `pinhole` (default) for standard lenses, `simple_radial` or `radial` for barrel or pincushion distortion, `simple_divisional` for fisheye lenses.
- **Distorted weights**: set `use_distorted_weights` to `true` to use weights trained on distorted images, for fisheye and wide-angle photos.
- **Known focal length**: pass `focal_length_prior` in pixels to use it as a strong prior; the default `0` turns this off.
- **Visualization**: `return_visualization` (default `true`) adds an image of the predicted up-vectors, latitude and confidence maps overlaid on the input.

## Use Cases
1. **Horizon and tilt correction**: read roll and pitch to level or straighten photos.
2. **3D and AR pipelines**: get an intrinsic matrix for photos that have no EXIF focal length.
3. **Dataset annotation**: add field of view and camera orientation to large image collections.
4. **Wide-angle and fisheye photos**: fit a distortion camera model with the distorted weights.

## Visual Examples
### Example Input
Image:

![Example input: a furnished interior room photo](https://blog.api.market/wp-content/uploads/2026/04/interior-input-api-market.jpg)

Settings: `camera_model` `pinhole`, `focal_length_prior` `0` (no prior), `return_visualization` `true`, `use_distorted_weights` `false`.

### Example Output
Visualization:

![GeoCalib visualization of the predicted up-vectors, latitude and confidence fields for the interior photo](https://blog.api.market/wp-content/uploads/2026/11/geocalib-output-4qzvxeyb-api-market.png)

Calibration JSON (decoded from `calibration_json`, shortened):
```json
{
  "model": { "name": "GeoCalib", "paper": "Single-Image Camera Calibration with Geometric Optimization (ECCV 2024)" },
  "settings": { "camera_model": "pinhole", "weights": "pinhole", "focal_length_prior": null },
  "camera": {
    "image_width": 2160,
    "image_height": 1440,
    "focal_length_x": 956.0895385742188,
    "focal_length_y": 956.089599609375,
    "principal_point_x": 1080.0,
    "principal_point_y": 720.0,
    "vertical_fov_deg": 73.96442588058073,
    "horizontal_fov_deg": 96.96512889173368,
    "intrinsic_matrix_K": [[956.0895385742188, 0.0, 1080.0], [0.0, 956.089599609375, 720.0], [0.0, 0.0, 1.0]]
  },
  "gravity": {
    "roll_deg": 0.007448501382777411,
    "pitch_deg": 0.05172844434919818,
    "roll_rad": 0.00013000087346881628,
    "pitch_rad": 0.0009028316708281636,
    "gravity_vector_3d": [-0.0001300138101214543, -0.9999995827674866, 0.0009028315544128418]
  },
  "uncertainty": {
    "roll_uncertainty_deg": 0.7676019519703031,
    "pitch_uncertainty_deg": 0.9834191744348983,
    "focal_uncertainty_px": 220.77784729003906,
    "vfov_uncertainty_deg": 17.98286184872078,
    "gravity_uncertainty": 0.018392225727438927
  },
  "performance": { "inference_time_seconds": 1.746, "device": "cuda" }
}
```

The full document also contains `gravity.rotation_matrix_R` and author details in `model`.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Input image (JPEG, PNG, WebP). The model estimates camera intrinsics and gravity direction from this single image |
| `camera_model` | string | No | `pinhole` | `pinhole`, `simple_radial`, `radial`, `simple_divisional` | Camera model to fit. `pinhole` for standard lenses, `simple_radial` or `radial` for barrel/pincushion distortion, `simple_divisional` for fisheye lenses |
| `use_distorted_weights` | boolean | No | `false` |  | Use the "distorted" pretrained weights instead of "pinhole". Enable this for images with visible lens distortion (fisheye, wide-angle) |
| `focal_length_prior` | number | No | `0` | minimum 0 | Optional known focal length in pixels, used as a strong prior to improve gravity estimation. Set to 0 to disable |
| `return_visualization` | boolean | No | `true` |  | Generate a visualization image showing the predicted geometric fields (up-vectors, latitude, confidence maps) overlaid on the input |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.001 per API unit.
- **1 API unit = 1 successful request with up to 4 seconds of processing.** A longer job bills one more unit for each started block of 4 seconds (for example, 10 seconds of processing is 3 units, $0.003).
- **Example cost**: the example request took 7.72 seconds of processing, which is 2 units, so $0.002.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/single-image-camera-calibration-visionaix-geocalib`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/single-image-camera-calibration-visionaix-geocalib/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "792fe7f7e327568ceca25af153d9207791d0b6bca0b1c5720e482217fb24d551",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/04/interior-input-api-market.jpg",
      "camera_model": "pinhole",
      "focal_length_prior": 0,
      "return_visualization": true,
      "use_distorted_weights": false
    }
  }'
```

Response (201 Created):
```json
{
  "id": "4qzvxeyby1rg80d1mvpsds29nw",
  "version": "792fe7f7e327568ceca25af153d9207791d0b6bca0b1c5720e482217fb24d551",
  "status": "starting",
  "created_at": "2026-11-04T14:19:24.528Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/single-image-camera-calibration-visionaix-geocalib/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK, `calibration_json` shortened):
```json
{
  "id": "4qzvxeyby1rg80d1mvpsds29nw",
  "status": "succeeded",
  "output": {
    "calibration_json": "data:application/json;base64,ewogICJtb2RlbCI6IHsKICAgICJuYW1lIjogIkdlb0NhbGliIiwK...",
    "visualization": "https://blog.api.market/wp-content/uploads/2026/11/geocalib-output-4qzvxeyb-api-market.png"
  },
  "error": null,
  "created_at": "2026-11-04T14:19:24.528Z",
  "started_at": "2026-11-04T14:20:50.362Z",
  "completed_at": "2026-11-04T14:20:58.080Z"
}
```

`output` is an object with two fields. `calibration_json` is a `data:application/json;base64,...` URI: base64-decode the part after the comma to get the calibration JSON shown above. `visualization` is the PNG visualization; the API can return it inline as a `data:image/png;base64,...` URI as well, so handle both a URL and a data URI.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image` or a `camera_model` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/single-image-camera-calibration-visionaix-geocalib";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "792fe7f7e327568ceca25af153d9207791d0b6bca0b1c5720e482217fb24d551", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

function decodeCalibration(dataUri) {
  const base64 = dataUri.slice(dataUri.indexOf(",") + 1);
  return JSON.parse(Buffer.from(base64, "base64").toString("utf8"));
}

createAndWaitForPrediction({
  "image": "https://blog.api.market/wp-content/uploads/2026/04/interior-input-api-market.jpg",
  "camera_model": "pinhole",
  "focal_length_prior": 0,
  "return_visualization": true,
  "use_distorted_weights": false
}).then((output) => {
  const calibration = decodeCalibration(output.calibration_json);
  console.log(calibration.camera.vertical_fov_deg, calibration.gravity.roll_deg, calibration.gravity.pitch_deg);
});
```

#### Python
```python
import base64
import json
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/single-image-camera-calibration-visionaix-geocalib"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "792fe7f7e327568ceca25af153d9207791d0b6bca0b1c5720e482217fb24d551", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


def decode_calibration(data_uri):
    return json.loads(base64.b64decode(data_uri.split(",", 1)[1]))


output = create_and_wait_for_prediction({
    "image": "https://blog.api.market/wp-content/uploads/2026/04/interior-input-api-market.jpg",
    "camera_model": "pinhole",
    "focal_length_prior": 0,
    "return_visualization": True,
    "use_distorted_weights": False
})
calibration = decode_calibration(output["calibration_json"])
print(calibration["camera"]["vertical_fov_deg"], calibration["gravity"]["roll_deg"], calibration["gravity"]["pitch_deg"])
```

## FAQ
- **How do I read the calibration result?**
  - `output.calibration_json` is a base64 data URI. Decode the text after the comma to get JSON with `camera`, `gravity`, `uncertainty`, `settings` and `performance` blocks.
- **Which camera model should I pick?**
  - `pinhole` for standard lenses, `simple_radial` or `radial` for photos with barrel or pincushion distortion, and `simple_divisional` for fisheye lenses. For distorted photos also set `use_distorted_weights` to `true`.
- **I already know the focal length. Can I use it?**
  - Yes. Pass it in pixels as `focal_length_prior`. The optimizer uses it as a strong prior, which improves the gravity (roll and pitch) estimate.
- **How much does one image cost?**
  - $0.001 for each started block of 4 seconds of processing. The example image (2160 x 1440) took 7.72 seconds, so it cost 2 units ($0.002).
- **Can I skip the visualization image?**
  - Set `return_visualization` to `false` if you only need the numbers.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page.


Estimate camera intrinsics and gravity direction (roll and pitch) from one image with GeoCalib, with uncertainty for each value. $0.001 per 4 seconds of processing, pay as you go.