Name: OpenAI GPT-5 Structured Output LLM API
Brand: magicapi
SKU: api-magicapi-ai-structured-output-enhanced-tools-openai-gpt-5-structured
Availability: InStock
Author: API Market

Shashank Agarwal

# 🤖 Structured Output LLM API (OpenAI GPT-5)

## Overview
GPT-5 is a language model from OpenAI. This endpoint runs GPT-5, GPT-5 mini or GPT-5 nano with support for structured outputs, web search and custom tools.

Send a `prompt` (or an `input_item_list`), optionally with images and a schema. Each request returns an object with the response `text`, the parsed `json_output` when you set a schema, and a `response_id` you can continue from.

## Features
- **Three models**: `gpt-5` (default), `gpt-5-mini` and `gpt-5-nano`.
- **Structured output**: `simple_schema` builds a JSON schema from a list such as `["animal", "animal_count:int"]`; `json_schema` takes a full JSON schema for nested objects.
- **Image input**: send image URLs in `image_input`.
- **Web search**: set `enable_web_search` to let the model search the web.
- **Tools**: pass tool definitions in `tools`.
- **Reasoning and verbosity**: `reasoning_effort` (`minimal` default, `low`, `medium`, `high`) and `verbosity` (`low`, `medium` default, `high`).
- **Conversations**: continue from an earlier answer with `previous_response_id`; set a system message with `instructions`.

## Use Cases
1. **Data extraction**: turn text or images into JSON with the fields your code expects.
2. **Image description and tagging**: structured labels for photos in a catalog or archive.
3. **Classification and routing**: return a category and a confidence field to drive a workflow.
4. **Research with sources**: answers that use web search when `enable_web_search` is on.

## Visual Examples
### Example Input
Our giraffe photo with the prompt "Describe the main animal in this photo." and a `simple_schema` of four fields, on `gpt-5-nano` with `reasoning_effort` `minimal` and `verbosity` `low`.

![Input image: a giraffe standing in a grassy savanna](https://blog.api.market/wp-content/uploads/2026/10/rmgb-input-api-market.jpg)

```json
{
  "model": "gpt-5-nano",
  "prompt": "Describe the main animal in this photo.",
  "image_input": [
    "https://blog.api.market/wp-content/uploads/2026/10/rmgb-input-api-market.jpg"
  ],
  "simple_schema": [
    "animal",
    "animal_count:int",
    "setting",
    "visible_colors:list"
  ],
  "reasoning_effort": "minimal",
  "verbosity": "low"
}
```

### Example Output
```json
{
  "json_output": {
    "animal": "Giraffe",
    "animal_count": 1,
    "setting": "Open savanna with tall grasses and scattered trees; group of zebras in the background",
    "visible_colors": [
      "brown",
      "tan",
      "cream",
      "white",
      "black"
    ]
  },
  "response_id": "resp_0df82beff3c9100e006aeb9981c55487d1abb4fad81a5a7162",
  "text": "{\"animal\":\"Giraffe\",\"animal_count\":1,\"setting\":\"Open savanna with tall grasses and scattered trees; group of zebras in the background\",\"visible_colors\":[\"brown\",\"tan\",\"cream\",\"white\",\"black\"]}"
}
```

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | string | No | `gpt-5` | `gpt-5`, `gpt-5-mini`, `gpt-5-nano` | GPT-5 model to use. |
| `prompt` | string | No | none |  | A simple text input to the model, equivalent to a text input with the user role. Ignored if input_item_list is provided. |
| `instructions` | string | No | none |  | A system (or developer) message inserted into the model's context. When used with previous_response_id, the instructions from a previous response are not carried over to the next response. |
| `image_input` | array of URLs | No | `[]` |  | List of image URLs to send to the model. |
| `reasoning_effort` | string | No | `minimal` | `minimal`, `low`, `medium`, `high` | Constrains reasoning effort. minimal answers faster without extensive reasoning first. Lower effort means faster responses and fewer tokens used on reasoning. At higher efforts you may need to raise max_output_tokens to avoid empty responses (where all tokens are used on reasoning). |
| `verbosity` | string | No | `medium` | `low`, `medium`, `high` | Constrains the verbosity of the response. Lower values give more concise responses, higher values more comprehensive ones. |
| `enable_web_search` | boolean | No | `false` |  | Allow the model to use web search for the response. |
| `simple_schema` | array of strings | No | `[]` |  | Create a JSON schema for the output from a simple list of field specifications. Strings: 'thing' (defaults to string), 'thing:str', 'thing:string'. Booleans: 'is_a_thing:bool' or 'is_a_thing:boolean'. Numbers: 'count:number', 'count:int'. Lists: 'things:list' (defaults to list of strings), 'things:list:str', 'number_things:list:number', etc. Nested objects are not supported; use json_schema instead. |
| `input_item_list` | array of objects | No | `[]` |  | A list of one or more input items with different content types, in the format of the input parameter of OpenAI's Responses API. Similar to a messages list, with more flexibility in content types. When set, prompt is ignored. |
| `previous_response_id` | string | No | none |  | The ID of a previous response to continue from. |
| `tools` | array of objects | No | `[]` |  | Tools to make available to the model, as a list of tool definition objects. |
| `json_schema` | object | No | `{}` |  | A JSON schema the response must conform to. Pass a raw JSON schema (e.g. {"type": "object", "properties": {...}, "required": [...], "additionalProperties": false}), a Responses API format block ({"type": "json_schema", "name": "...", "schema": {...}}) or a fully wrapped value ({"format": {...}}). For simple data structures, simple_schema is easier. |
| `max_output_tokens` | integer | No | none |  | Maximum number of completion tokens to generate. At higher reasoning efforts you may need to increase it to avoid empty responses (where all tokens are used on reasoning). |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.001 per API unit.
- **Metered billing**: a request is billed for the input and output tokens it uses, summed, then rounded up to a whole API unit.
- **Price by model** (per million tokens):

| `model` | Input tokens | Output tokens |
| --- | --- | --- |
| `gpt-5` | $1.48 | $11.8 |
| `gpt-5-mini` | $0.295 | $2.36 |
| `gpt-5-nano` | $0.0589 | $0.471 |

- When `model` is left out, `gpt-5` applies.
- Token counts are the ones the model reports for the request; input tokens include images. If a response reports no token counts, it is billed as at least 30,000 input and 8,000 output tokens.
- **Example cost**: the example used 1,121 input tokens and 68 output tokens on `gpt-5-nano`: 1,121 x $0.0589 / 1,000,000 + 68 x $0.471 / 1,000,000 = $0.000098, rounded up to 1 unit ($0.001).
- **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/ai-structured-output-enhanced-tools-openai-gpt-5-structured`

### 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/ai-structured-output-enhanced-tools-openai-gpt-5-structured/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "openai/gpt-5-structured",
    "input": {
      "model": "gpt-5-nano",
      "prompt": "Describe the main animal in this photo.",
      "image_input": [
        "https://blog.api.market/wp-content/uploads/2026/10/rmgb-input-api-market.jpg"
      ],
      "simple_schema": [
        "animal",
        "animal_count:int",
        "setting",
        "visible_colors:list"
      ],
      "reasoning_effort": "minimal",
      "verbosity": "low"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "r18724msxdrmw0d1n17sp0jcg4",
  "version": "openai/gpt-5-structured",
  "status": "starting",
  "created_at": "2026-11-04T20:45:51.467Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-structured-output-enhanced-tools-openai-gpt-5-structured/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "r18724msxdrmw0d1n17sp0jcg4",
  "status": "succeeded",
  "output": {
    "json_output": {
      "animal": "Giraffe",
      "animal_count": 1,
      "setting": "Open savanna with tall grasses and scattered trees; group of zebras in the background",
      "visible_colors": [
        "brown",
        "tan",
        "cream",
        "white",
        "black"
      ]
    },
    "response_id": "resp_0df82beff3c9100e006aeb9981c55487d1abb4fad81a5a7162",
    "text": "{\"animal\":\"Giraffe\",\"animal_count\":1,\"setting\":\"Open savanna with tall grasses and scattered trees; group of zebras in the background\",\"visible_colors\":[\"brown\",\"tan\",\"cream\",\"white\",\"black\"]}"
  },
  "error": null,
  "created_at": "2026-11-04T20:45:51.467Z",
  "started_at": "2026-11-04T20:45:51.573Z",
  "completed_at": "2026-11-04T20:45:54.945Z"
}
```

`output` is an object: `text` is the response text, `json_output` is the parsed JSON when you set `simple_schema` or `json_schema`, and `response_id` identifies the response for `previous_response_id`.

### 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 `model` that is not in the list or an invalid `json_schema`.
- **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/ai-structured-output-enhanced-tools-openai-gpt-5-structured";

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-5-structured", 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({
  "model": "gpt-5-nano",
  "prompt": "Describe the main animal in this photo.",
  "image_input": [
    "https://blog.api.market/wp-content/uploads/2026/10/rmgb-input-api-market.jpg"
  ],
  "simple_schema": [
    "animal",
    "animal_count:int",
    "setting",
    "visible_colors:list"
  ],
  "reasoning_effort": "minimal",
  "verbosity": "low"
}).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/ai-structured-output-enhanced-tools-openai-gpt-5-structured"


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-5-structured", "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(create_and_wait_for_prediction({
    "model": "gpt-5-nano",
    "prompt": "Describe the main animal in this photo.",
    "image_input": [
        "https://blog.api.market/wp-content/uploads/2026/10/rmgb-input-api-market.jpg"
    ],
    "simple_schema": [
        "animal",
        "animal_count:int",
        "setting",
        "visible_colors:list"
    ],
    "reasoning_effort": "minimal",
    "verbosity": "low"
}))
```

## FAQ
- **How do I get JSON back?**
  - List the fields in `simple_schema`, for example `["name", "age:int", "tags:list"]`, or pass a full schema in `json_schema` for nested objects. The parsed result is in `output.json_output` and the raw text in `output.text`.
- **Which model should I use?**
  - `gpt-5` (default) is the most capable and the most expensive. `gpt-5-mini` and `gpt-5-nano` cost less per token (see the pricing table); the example used `gpt-5-nano`.
- **Why is my response empty?**
  - At higher `reasoning_effort` all tokens can go to reasoning. Raise `max_output_tokens` or lower `reasoning_effort`.
- **Can I continue a conversation?**
  - Yes. Send the `response_id` from a previous output as `previous_response_id`. Instructions from the previous response are not carried over, so send `instructions` again if you need them.
- **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.


Get JSON that matches your schema from OpenAI's GPT-5, GPT-5 mini or GPT-5 nano, with image input, web search and tools. From $0.0589 per million input tokens, pay as you go.