Name: GPT-4.1 mini API: Fast Text and Vision Chat by OpenAI
Brand: magicapi
SKU: api-magicapi-fast-affordable-ai-text-generation-openai-gpt-4-1-mini
Availability: InStock
Author: API Market

Shashank Agarwal

# 💬 Text and Vision Chat API (OpenAI GPT-4.1 mini)

## Overview
GPT-4.1 mini is a model from OpenAI. Its developer describes it as a fast, affordable version of GPT-4.1. It answers text prompts and can read the images you pass in `image_input`.

Send a `prompt` with an optional `system_prompt`, or a full `messages` list for multi-turn chat. Tune the response with `temperature`, `top_p`, `presence_penalty`, `frequency_penalty` and `max_completion_tokens` (default 4096). The response `output` is a list of text chunks; join them to get the full answer.

## Features
- **Prompt or chat**: send a single `prompt` with a `system_prompt`, or a `messages` list such as `[{"role": "user", "content": "Hello, how are you?"}]`. When `messages` is set, `prompt` and `system_prompt` are ignored.
- **Image input**: pass one or more image URLs in `image_input` and ask about them.
- **Sampling controls**: `temperature` 0 to 2, `top_p` 0 to 1, `presence_penalty` and `frequency_penalty` -2 to 2.
- **Length limit**: `max_completion_tokens` caps the response (default 4096).

## Use Cases
1. **Image descriptions**: alt text, product image captions and detailed scene descriptions, as in the example.
2. **Chat assistants**: support bots and in-app helpers that need quick, low-cost answers.
3. **Text processing**: summaries, rewrites, classification and extraction from documents.
4. **Drafting**: emails, product descriptions and short articles.

## Visual Examples
### Example Input
A prompt, a system prompt and one image:

![Example input image: a painting of an elderly man and a young woman seated facing each other](https://blog.api.market/wp-content/uploads/2026/10/gpt-4-1-mini-input-api-market.jpg)

```json
{
  "prompt": "Explain this image in excruciating detail",
  "image_input": [
    "https://blog.api.market/wp-content/uploads/2026/10/gpt-4-1-mini-input-api-market.jpg"
  ],
  "temperature": 1,
  "system_prompt": "You are a helpful assistant."
}
```

### Example Output
The output chunks joined into one text:

```text
This image is a hyper-realistic painting depicting two individuals seated facing each other in what appears to be an intimate or serious conversation. The painting is executed with remarkable attention to minute detail, capturing textures, light reflections, and fabric folds with an oil painting technique.

### Composition and Subjects:
1. **Left Subject: Elderly Man**
   - The man appears to be elderly, characterized by thick, white, wavy hair that extends outward, and a matching white mustache. 
   - He is wearing dark, rectangular framed sunglasses that reflect light subtly, suggesting ambient lighting in the environment.
   - His facial expression is calm and contemplative, highlighted by the wrinkles on his forehead and around his eyes, indicating age and experience.
   - He is dressed in a layered outfit: a dark, almost black jacket with shiny buttons over a dark grey or blue sweater or t-shirt. The jacket has visible fold lines, seams, and textures that add to the realism.
   - His hands are interlocked and resting on one thigh, conveying a relaxed yet attentive posture. The skin on his hands is detailed with veins and age spots.

2. **Right Subject: Young Woman**
   - The woman is younger, with a smooth complexion and muscular, fit arms and torso, evident from her attire.
   - Her hair is light brown, tied back in a casual ponytail with some volume, held by a black hairband.
   - She wears black sunglasses with a slightly different, more angular frame than the man's, darker lenses that obscure her eyes.
   - She sports a sporty, black, sleeveless crop-top with a horizontal stripe pattern in red, white, and green along the bust area. The top highlights her athletic build.
   - Her high-waisted, slim black pants further outline her figure.
   - She is sitting with a slight forward lean, feet planted on the floor, and her hands resting on her thighs, suggesting attentiveness and engagement in the conversation.
   - Her lips are painted a bold red, contrasting with her neutral skin tone and the muted background.

### Setting and Background:
- Both subjects are seated on mustard-yellow cushions that provide a soft, inviting backdrop against the neutral, muted gray-beige background wall.
- The chairs or sofa they sit on is only partially visible, covered with the yellow cushions.
- The background is plain, which directs full attention to the interaction and detail of the two figures.

### Lighting and Texture:
- The lighting is soft and even, likely mimicking indoor light that avoids harsh shadows but clearly defines form and texture.
- The skin tones are natural with subtle shadings that show the three-dimensional structure of muscles, veins, and wrinkles.
- The clothing is painted with distinct brushstrokes that convey the different materials: soft fabric of the sweater, structured jacket, smooth sportswear, and shiny sunglasses.

### Mood and Possible Interpretation:
- The mood of the painting appears intimate and enigmatic: two people from very different generations and possibly very different backgrounds are engaged deeply.
- The sunglasses on both obscure eye contact, adding an element of mystery or emotional distance despite their physical proximity and engaged postures.
- The contrast between the elderly man's worn, layered clothing and the woman's modern, athletic attire perhaps symbolizes a meeting of different eras or mindsets.
- Overall, the painting elegantly explores themes of communication, generational dialogue, and the interplay between appearance and perception.

If you want, I can analyze further aspects such as brush technique, color theory, or symbolic meanings!
```

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | No | none |  | The prompt to send to the model. Do not use if using messages. |
| `system_prompt` | string | No | none |  | System prompt to set the assistant's behavior |
| `messages` | array of objects | No | `[]` |  | A list of chat messages, for example: [{"role": "user", "content": "Hello, how are you?"}]. If provided, prompt and system_prompt are ignored. |
| `image_input` | array of URLs | No | `[]` |  | List of images to send to the model |
| `temperature` | number | No | `1` | `0` to `2` | Sampling temperature between 0 and 2 |
| `max_completion_tokens` | integer | No | `4096` |  | Maximum number of completion tokens to generate |
| `top_p` | number | No | `1` | `0` to `1` | Nucleus sampling parameter: the model considers the tokens within the top_p probability mass (0.1 means only the tokens in the top 10% probability mass are considered). |
| `frequency_penalty` | number | No | `0` | `-2` to `2` | Frequency penalty: positive values penalize the repetition of tokens. |
| `presence_penalty` | number | No | `0` | `-2` to `2` | Presence penalty: positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.002 per API unit.
- **1 API unit = 1,000 weighted tokens; an output token counts 1, an input token counts 0.25.**
- That is **$0.50 per million input tokens** and **$2 per million output tokens**.
- Images in `image_input` count toward input tokens. Each request is rounded up to a whole unit.
- **Example cost**: the example request (a short prompt and one image) used 1,166 input tokens and 707 output tokens: 1,166 x 0.25 + 707 = 998.5 weighted tokens, rounded up to 1 unit = **$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/fast-affordable-ai-text-generation-openai-gpt-4-1-mini`

### 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. Most responses finish within a minute; the example took about 19 seconds.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/fast-affordable-ai-text-generation-openai-gpt-4-1-mini/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "openai/gpt-4.1-mini",
    "input": {
      "prompt": "Explain this image in excruciating detail",
      "image_input": [
        "https://blog.api.market/wp-content/uploads/2026/10/gpt-4-1-mini-input-api-market.jpg"
      ],
      "temperature": 1,
      "system_prompt": "You are a helpful assistant."
    }
  }'
```

Response (201 Created):
```json
{
  "id": "8a55empxsxrmt0d1c6stnnde7m",
  "version": "openai/gpt-4.1-mini",
  "status": "starting",
  "created_at": "2026-10-22T03:42:20.297Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/fast-affordable-ai-text-generation-openai-gpt-4-1-mini/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "8a55empxsxrmt0d1c6stnnde7m",
  "status": "succeeded",
  "output": [
    "",
    "This",
    " image",
    " is",
    " a",
    " hyper",
    "-real",
    "istic",
    " painting",
    " depicting",
    " two",
    " individuals"
  ],
  "error": null,
  "created_at": "2026-10-22T03:42:20.297Z",
  "started_at": "2026-10-22T03:42:20.946Z",
  "completed_at": "2026-10-22T03:42:39.719Z"
}
```

`output` is a list of text chunks (abridged above; the example response has 708 chunks). Join them in order to get the full response text.

### 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 `temperature` above 2 or an `image_input` entry that is not a URL.
- **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/fast-affordable-ai-text-generation-openai-gpt-4-1-mini";

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: "openai/gpt-4.1-mini", 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");
}

createAndWaitForPrediction({
    "prompt": "Explain this image in excruciating detail",
    "image_input": [
      "https://blog.api.market/wp-content/uploads/2026/10/gpt-4-1-mini-input-api-market.jpg"
    ],
    "temperature": 1,
    "system_prompt": "You are a helpful assistant."
  }).then((output) => console.log(output.join("")));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/fast-affordable-ai-text-generation-openai-gpt-4-1-mini"


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": "openai/gpt-4.1-mini", "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")


print("".join(create_and_wait_for_prediction({
    "prompt": "Explain this image in excruciating detail",
    "image_input": [
        "https://blog.api.market/wp-content/uploads/2026/10/gpt-4-1-mini-input-api-market.jpg"
    ],
    "temperature": 1,
    "system_prompt": "You are a helpful assistant."
})))
```

## FAQ
- **How do I get the full answer from `output`?**
  - `output` is a list of text chunks. Join them in order, for example `output.join("")` in JavaScript or `"".join(output)` in Python.
- **Can I send a conversation history?**
  - Yes. Send `messages` as a list of `{"role": ..., "content": ...}` objects. When `messages` is set, `prompt` and `system_prompt` are ignored.
- **Can it read images?**
  - Yes. Put one or more image URLs in `image_input` and ask about them in the prompt. Images add to the input token count.
- **How much does a request cost?**
  - $0.50 per million input tokens and $2 per million output tokens, rounded up to a whole unit of $0.002 per request. The example request cost $0.002.
- **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`.
- **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. You can also email our support team at hello@magicapi.com.


Generate text and describe images with OpenAI GPT-4.1 mini: prompts, system prompts, chat messages and image input. Pay as you go, no monthly fee.