Name: Granite Vision 4.1 4B API: Chart and Document Extraction
Brand: magicapi
SKU: api-magicapi-structured-document-extraction-api-ibm-granite-granite-vision-4-1-4b
Availability: InStock
Author: API Market

Shashank Agarwal

# 📋 Chart and Document Extraction API (IBM Granite Vision 4.1 4B)

## Overview
Granite Vision 4.1 4B is a 4B-parameter vision-language model from IBM. Its developer describes it as delivering frontier-level performance on structured document extraction: chart extraction, table extraction and semantic key-value pair extraction.

Send image URLs in `images` with a text `prompt`, or a `messages` array for chat. The example uses the task tag `<chart2summary>` as the prompt, which returns a prose summary of a chart. The model returns generated text.

## Features
- **Structured document extraction**: charts, tables and key-value pairs in document images.
- **Image input**: `images` takes an array of image URLs.
- **Prompt or chat**: send a single `prompt` (with optional `system_prompt`) or a `messages` array.
- **Length controls**: `max_completion_tokens` caps the generated tokens; `min_tokens` sets a minimum. `max_tokens` is deprecated.
- **Sampling controls**: `temperature`, `top_p`, `top_k`, `presence_penalty`, `frequency_penalty`, `repetition_penalty`, `stop` and `seed`.

## Use Cases
1. **Chart summaries**: describe a chart's title, axes, series and values in text.
2. **Table extraction**: read tables from scanned reports and screenshots.
3. **Form and invoice fields**: pull key-value pairs such as dates, totals and names.
4. **Report digitization**: turn charts and tables in PDFs rendered as images into text for search.

## Visual Examples
### Example Input
![Example input: a bar chart of unemployment rates for New Jersey and neighboring states, 2017 vs 2018](https://blog.api.market/wp-content/uploads/2026/10/granite-vision-4-1-4b-input-api-market.jpg)

Prompt: `<chart2summary>`. Settings: `temperature` 0.2, `top_p` 0.9, `top_k` 50, `min_tokens` 0, `stream` `false`, `add_generation_prompt` `true`; `messages` and `stop` empty.

### Example Output
The chunks of this run joined into one answer:

````markdown
The chart image is a bar chart titled "Unemployment Rate (NJ and Neighbors) 2017 vs 2018." It compares the unemployment rates of New Jersey (NJ) and its neighboring states (CT, DE, NY, PA) for the years 2017 and 2018. The x-axis represents the states, while the y-axis represents the unemployment rate in percentage, ranging from 0.0 to 6.0.

Each state has two bars: a light pink bar for the year 2017 and a dark red bar for the year 2018. The exact unemployment rates are labeled on top of each bar. For 2017, the unemployment rates are as follows: NJ at 4.6%, CT at 4.7%, DE at 4.5%, NY at 4.7%, and PA at 4.9%. For 2018, the unemployment rates are: NJ at 4.1%, CT at 4.1%, DE at 3.8%, NY at 4.1%, and PA at 4.3%.

The chart visually indicates that unemployment rates have decreased from 2017 to 2018 across all the states. New Jersey's unemployment rate in 2018 is right in line with its neighboring states, being better than Pennsylvania (PA) and worse than Delaware (DE). The highest unemployment rate in 2017 was in Pennsylvania at 4.9%, while the lowest was in Delaware at 4.5%. In 2018, the highest unemployment rate was in Pennsylvania at 4.3%, and the lowest was in Delaware at 3.8%.

The chart effectively uses color differentiation to distinguish between the two years, with light pink representing 2017 and dark red representing 2018. The bars are neatly arranged side by side for each state, making it easy to compare the unemployment rates between the two years. The chart also includes a legend in the top right corner to indicate the color coding for the years.
````

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | No | none |  | Completion API user prompt. The example uses the task tag `<chart2summary>`. |
| `messages` | array of objects | No | none |  | Chat messages, as message objects (for example `{"role": "user", "content": "..."}`). Use instead of `prompt` for multi-turn chat. |
| `images` | array of URLs | No | none |  | Image input, as an array of image URLs. |
| `system_prompt` | string | No | none |  | Completion API system prompt. The chat template provides a good default. |
| `chat_template` | string | No | none |  | A template to format the prompt with. If not specified, the chat template provided by the model will be used. |
| `add_generation_prompt` | boolean | No | `true` |  | Add generation prompt. Passed to the chat template. |
| `chat_template_kwargs` | object | No | none |  | Additional arguments to be passed to the chat template. |
| `min_tokens` | integer | No | `0` |  | The minimum number of tokens the model should generate as output. |
| `max_tokens` | integer | No | none |  | Deprecated in favor of `max_completion_tokens`. |
| `max_completion_tokens` | integer | No | none |  | An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. |
| `temperature` | number | No | none |  | The value used to modulate the next token probabilities. |
| `top_p` | number | No | none |  | A probability threshold for generating the output. If < 1.0, only keep the top tokens with cumulative probability >= top_p (nucleus filtering). |
| `top_k` | integer | No | none |  | The number of highest probability tokens to consider for generating the output. If > 0, only keep the top k tokens with highest probability (top-k filtering). |
| `presence_penalty` | number | No | none |  | Presence penalty |
| `frequency_penalty` | number | No | none |  | Frequency penalty |
| `repetition_penalty` | number | No | none |  | Repetition penalty |
| `stop` | array of strings | No | none |  | A list of sequences to stop generation at. For example, `["<end>","<stop>"]` stops generation at the first instance of `<end>` or `<stop>`. |
| `seed` | integer | No | none |  | Random seed. Leave unspecified to randomize the seed. |
| `stream` | boolean | No | none |  | Request a streaming response. Results are read by polling GET `/predictions/{id}`, so leave this `false`. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0032 per API unit.
- **1 API unit = 10,000 weighted tokens**; an output token counts 1, an input token counts 0.24.
- That is **$0.0768 per million input tokens** and **$0.32 per million output tokens**.
- Each request is rounded up to a whole API unit, so the smallest charge per request is $0.0032.
- **Example cost**: the example request used 974 input tokens and 420 output tokens. 974 x 0.24 + 420 = 653.76 weighted tokens, rounded up to 1 API unit = **$0.0032**.
- **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/structured-document-extraction-api-ibm-granite-granite-vision-4-1-4b`

### 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/structured-document-extraction-api-ibm-granite-granite-vision-4-1-4b/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ibm-granite/granite-vision-4.1-4b",
    "input": {
      "stop": [],
      "top_k": 50,
      "top_p": 0.9,
      "images": [
        "https://blog.api.market/wp-content/uploads/2026/10/granite-vision-4-1-4b-input-api-market.jpg"
      ],
      "prompt": "<chart2summary>",
      "stream": false,
      "messages": [],
      "min_tokens": 0,
      "temperature": 0.2,
      "chat_template_kwargs": {},
      "add_generation_prompt": true
    }
  }'
```

Response (201 Created):
```json
{
  "id": "tkbva9hcp5rmw0d1d109rbwvy8",
  "version": "ibm-granite/granite-vision-4.1-4b",
  "status": "starting",
  "created_at": "2026-10-23T10:13:18.898Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/structured-document-extraction-api-ibm-granite-granite-vision-4-1-4b/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "tkbva9hcp5rmw0d1d109rbwvy8",
  "status": "succeeded",
  "output": [
    "The chart image is a bar chart titled \"Unemployment Rate (NJ and Neighbors) 2017 vs 2018.\" It compares the unemployment rates of New Jersey (NJ) and its neighboring states (CT, DE, NY, PA) for the years 2017 and 2018. The x-axis represents the states, while the y-axis represents the unemployment rate in percentage, ranging from 0.0 to 6.0.\n\nEach state has two bars: a light pink bar for the year 2017 and a dark red bar for the year 2018. The exact unemployment rates are labeled on top of each bar. For 2017, the unemployment rates are as follows: NJ at 4.6%, CT at 4.7%, DE at 4.5%, NY at 4.7%, and PA at 4.9%. For 2018, the unemployment rates are: NJ at 4.1%, CT at 4.1%, DE at 3.8%, NY at 4.1%, and PA at 4.3%.\n\nThe chart visually indicates that unemployment rates have decreased from 2017 to 2018 across all the states. New Jersey's unemployment rate in 2018 is right in line with its neighboring states, being better than Pennsylvania (PA) and worse than Delaware (DE). The highest unemployment rate in 2017 was in Pennsylvania at 4.9%, while the lowest was in Delaware at 4.5%. In 2018, the highest unemployment rate was in Pennsylvania at 4.3%, and the lowest was in Delaware at 3.8%.\n\nThe chart effectively uses color differentiation to distinguish between the two years, with light pink representing 2017 and dark red representing 2018. The bars are neatly arranged side by side for each state, making it easy to compare the unemployment rates between the two years. The chart also includes a legend in the top right corner to indicate the color coding for the years."
  ],
  "error": null,
  "created_at": "2026-10-23T10:13:18.898Z",
  "started_at": "2026-10-23T10:13:18.930Z",
  "completed_at": "2026-10-23T10:13:23.978Z"
}
```

`output` is an array of text chunks. Join them in order to get the full answer. The example above shows the chunks from this run already joined into one string.

### 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 `images` that is not an array of URLs.
- **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
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## 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/structured-document-extraction-api-ibm-granite-granite-vision-4-1-4b";

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: "ibm-granite/granite-vision-4.1-4b", 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.join("");
    }

    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");
}

createAndWaitForPrediction({
    "stop": [],
    "top_k": 50,
    "top_p": 0.9,
    "images": [
      "https://blog.api.market/wp-content/uploads/2026/10/granite-vision-4-1-4b-input-api-market.jpg"
    ],
    "prompt": "<chart2summary>",
    "stream": false,
    "messages": [],
    "min_tokens": 0,
    "temperature": 0.2,
    "chat_template_kwargs": {},
    "add_generation_prompt": true
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/structured-document-extraction-api-ibm-granite-granite-vision-4-1-4b"


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": "ibm-granite/granite-vision-4.1-4b", "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 "".join(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")


output = create_and_wait_for_prediction({
    "stop": [],
    "top_k": 50,
    "top_p": 0.9,
    "images": [
        "https://blog.api.market/wp-content/uploads/2026/10/granite-vision-4-1-4b-input-api-market.jpg"
    ],
    "prompt": "<chart2summary>",
    "stream": False,
    "messages": [],
    "min_tokens": 0,
    "temperature": 0.2,
    "chat_template_kwargs": {},
    "add_generation_prompt": True
})
print(output)
```

## FAQ
- **Why does `output` come back as a list?**
  - The answer is returned as an array of text chunks. Join them in order (`output.join("")` in JavaScript, `"".join(output)` in Python).
- **What should I put in `prompt`?**
  - Either a plain question about the image or a task tag. The example uses `<chart2summary>`, which returned a prose summary of the chart.
- **Should I use `prompt` or `messages`?**
  - Use `prompt` with `images` for a single request. Use `messages` to send a whole conversation as message objects with a `role` and `content`.
- **How do I limit the answer length?**
  - Set `max_completion_tokens`. `max_tokens` still exists but is deprecated in favor of `max_completion_tokens`.
- **How is a request billed?**
  - By weighted tokens at $0.0032 per 10,000: input tokens count 0.24 and output tokens count 1, rounded up to a whole unit per request. Most short requests cost $0.0032. Image tokens count as input tokens; the example read 974 input tokens and wrote 420 output tokens.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Extract charts, tables and key-value pairs from document images with IBM Granite Vision 4.1 4B. Pay as you go, no monthly fee.