Response

File Analysis

Image and file analysis using the Responses API.

The Responses API supports multimodal input via content blocks in the input array. Use input_image for images and input_file for documents and other files.

Endpoint and authentication are the same as Create a Response.

Confirm that the selected model supports the media type. A file_id must come from an upload accessible to the same service and account; this page does not define an upload endpoint, and another provider’s file ID is not interchangeable. URLs must be reachable by the server; local paths are not remote file URLs.

The current local gateway does not implement /v1/files uploads. Start with this page's URL or Base64 input examples. Use file_id examples only when your deployment provides uploads and you already have an ID accessible to the same account.

Content Block Types

Type	Description
input_text	Text prompt accompanying the media input
input_image	Image input via image_url or file_id; optional detail: auto, low, high, original
input_file	File input via file_url, file_id, or file_data; optional detail: auto, low, high

input_image

Field	Type	Required	Description
type	string	Yes	Always input_image
image_url	string	No	Fully qualified URL or base64 data URL
file_id	string	No	ID of a previously uploaded file
detail	string	No	auto (default), low, high, or original

For input_image, provide either image_url or file_id.

input_file

Field	Type	Required	Description
type	string	Yes	Always input_file
file_url	string	No	URL of the file to analyze
file_id	string	No	ID of a previously uploaded file
file_data	string	No	Inline file content
filename	string	No	Display name of the file
detail	string	No	auto (default), low, or high

For input_file, provide one of file_url, file_id, or file_data. When using file_data, also supply a filename with its extension.

Detail level

For GPT-5.6 and later models, detail: auto uses high-quality rendering, which may increase input token usage. Use low for lower cost or high for higher quality.

Image Analysis

Analyze an image by URL:

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "What is in this image?"},
        {
          "type": "input_image",
          "image_url": "https://example.com/image.jpg",
          "detail": "auto"
        }
      ]
    }
  ]
}

Analyze an image using a previously uploaded file ID:

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Describe this image in detail."},
        {
          "type": "input_image",
          "file_id": "file-abc123",
          "detail": "high"
        }
      ]
    }
  ]
}

File Analysis

Analyze a PDF or document by URL:

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Summarize the key points in this document."},
        {
          "type": "input_file",
          "file_url": "https://example.com/report.pdf",
          "detail": "auto"
        }
      ]
    }
  ]
}

Request Example

See language setup. Set API_KEY and replace model, file URL, and ID placeholders first. Each version displays the raw response to the same request.

cURL

curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/responses" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What is in this file?"
        },
        {
          "type": "input_file",
          "file_url": "https://www.example.com/document.pdf",
          "detail": "auto"
        }
      ]
    }
  ]
}'

Python

import os
import requests

headers = {
    'Authorization': 'Bearer ' + os.environ["API_KEY"],
    'Content-Type': 'application/json',
}
payload = {'model': 'gpt-5',
 'input': [{'role': 'user',
            'content': [{'type': 'input_text', 'text': 'What is in this file?'},
                        {'type': 'input_file',
                         'file_url': 'https://www.example.com/document.pdf',
                         'detail': 'auto'}]}]}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/responses', headers=headers,
    json=payload,
    timeout=180,
)
response.raise_for_status()
print(response.text)

JavaScript

if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What is in this file?"
        },
        {
          "type": "input_file",
          "file_url": "https://www.example.com/document.pdf",
          "detail": "auto"
        }
      ]
    }
  ]
}),
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());

Java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("Set API_KEY first.");
        }
        String payload = String.join("\n",
            "{",
            "  \"model\": \"gpt-5\",",
            "  \"input\": [",
            "    {",
            "      \"role\": \"user\",",
            "      \"content\": [",
            "        {",
            "          \"type\": \"input_text\",",
            "          \"text\": \"What is in this file?\"",
            "        },",
            "        {",
            "          \"type\": \"input_file\",",
            "          \"file_url\": \"https://www.example.com/document.pdf\",",
            "          \"detail\": \"auto\"",
            "        }",
            "      ]",
            "    }",
            "  ]",
            "}"
        );
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/responses"))
            .timeout(Duration.ofSeconds(180))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": "
                + response.body());
        }
        System.out.println(response.body());
    }
}

Response Example

{
  "code": 200,
  "data": {
    "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86",
    "object": "response",
    "status": "completed",
    "model": "gpt-5",
    "output": [
      {
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "The document covers quarterly financial results, including revenue growth of 12% year-over-year...",
            "annotations": []
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 8438,
      "output_tokens": 398,
      "total_tokens": 8836
    }
  }
}

Related Topics

• Create a Response — Text conversation and streaming
• Tool Calling — Custom function calling and returning results