Getting Started

The Gemina API enables you to extract structured data from documents programmatically. Upload documents via file or URL, receive structured JSON responses with extracted fields, coordinates, and confidence scores.

Base URLhttps://api.gemina.co

AuthenticationX-API-Key: your-api-key

Quick Start

Install the required package and set up your environment:

pip install requests

import os

BASE_URL = os.getenv("GEMINA_BASE_URL", "https://api.gemina.co")
API_KEY = os.getenv("GEMINA_API_KEY", "")
HEADERS = {"X-API-Key": API_KEY}

Authentication

All API requests require authentication via the X-API-Key header:

import requests

headers = {"X-API-Key": "your-api-key"}
response = requests.get(
    "https://api.gemina.co/api/v1/documents/",
    headers=headers
)

Upload Document

Upload a document for extraction using multipart form data:

import requests

url = "https://api.gemina.co/api/v1/documents/uploads"
headers = {"X-API-Key": "your-api-key"}

form_data = [
    ("extraction_types", "invoice_headers"),
    ("extraction_types", "invoice_line_items"),
    ("external_id", "inv-2025-0001"),
    ("model_type", "invictus"),
]

files = {
    "file": ("invoice.pdf", open("./invoice.pdf", "rb"), "application/pdf")
}

response = requests.post(url, headers=headers, data=form_data, files=files)
result = response.json()
print(result)

Response Format

Successful extractions return structured JSON with field values and confidence scores:

{
  "status": "success",
  "meta": {
    "documentId": "9860df92-64fe-4b53-9663-5c11b38a3051",
    "externalId": "inv-2025-0001",
    "filename": "invoice.pdf"
  },
  "data": {
    "extractions": [
      {
        "extractionType": "invoice_headers",
        "status": "success",
        "values": {
          "vendorName": {"value": "Acme Corp", "confidence": "high"},
          "invoiceNumber": {"value": "INV-001", "confidence": "high"},
          "totalAmount": {"value": 1250.00, "confidence": "high"}
        }
      }
    ]
  }
}

Quick Start

Install the required packages:

npm install axios form-data

import axios from "axios";

const BASE_URL = process.env.GEMINA_BASE_URL || "https://api.gemina.co";
const API_KEY = process.env.GEMINA_API_KEY || "";

const client = axios.create({
  baseURL: BASE_URL,
  headers: { "X-API-Key": API_KEY },
  timeout: 90_000,
});

Authentication

All API requests require authentication via the X-API-Key header:

import axios from "axios";

const client = axios.create({
  baseURL: "https://api.gemina.co",
  headers: { "X-API-Key": "your-api-key" },
});

const response = await client.get("/api/v1/documents/");

Upload Document

Upload a document for extraction using form data:

import fs from "fs";
import FormData from "form-data";
import axios from "axios";

const form = new FormData();
form.append("extraction_types", "invoice_headers");
form.append("extraction_types", "invoice_line_items");
form.append("external_id", "inv-2025-0001");
form.append("model_type", "invictus");
form.append("file", fs.createReadStream("./invoice.pdf"));

const response = await axios.post(
  "https://api.gemina.co/api/v1/documents/uploads",
  form,
  {
    headers: {
      "X-API-Key": "your-api-key",
      ...form.getHeaders(),
    },
  }
);

console.log(response.data);

Response Format

Successful extractions return structured JSON with field values and confidence scores:

{
  "status": "success",
  "meta": {
    "documentId": "9860df92-64fe-4b53-9663-5c11b38a3051",
    "externalId": "inv-2025-0001",
    "filename": "invoice.pdf"
  },
  "data": {
    "extractions": [
      {
        "extractionType": "invoice_headers",
        "status": "success",
        "values": {
          "vendorName": {"value": "Acme Corp", "confidence": "high"},
          "invoiceNumber": {"value": "INV-001", "confidence": "high"},
          "totalAmount": {"value": 1250.00, "confidence": "high"}
        }
      }
    ]
  }
}

Quick Start

Add OkHttp to your Maven or Gradle project:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

String BASE_URL = System.getenv("GEMINA_BASE_URL") != null
    ? System.getenv("GEMINA_BASE_URL") : "https://api.gemina.co";
String API_KEY = System.getenv("GEMINA_API_KEY");

OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(90, TimeUnit.SECONDS)
    .readTimeout(90, TimeUnit.SECONDS)
    .build();

Authentication

All API requests require authentication via the X-API-Key header:

Request request = new Request.Builder()
    .url("https://api.gemina.co/api/v1/documents/")
    .header("X-API-Key", "your-api-key")
    .get()
    .build();

Response response = client.newCall(request).execute();

Upload Document

Upload a document for extraction using multipart form data:

File invoiceFile = new File("invoice.pdf");

RequestBody requestBody = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("extraction_types", "invoice_headers")
    .addFormDataPart("extraction_types", "invoice_line_items")
    .addFormDataPart("external_id", "inv-2025-0001")
    .addFormDataPart("model_type", "invictus")
    .addFormDataPart("file", invoiceFile.getName(),
        RequestBody.create(invoiceFile, MediaType.parse("application/pdf")))
    .build();

Request request = new Request.Builder()
    .url("https://api.gemina.co/api/v1/documents/uploads")
    .header("X-API-Key", "your-api-key")
    .post(requestBody)
    .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

Response Format

Successful extractions return structured JSON with field values and confidence scores:

{
  "status": "success",
  "meta": {
    "documentId": "9860df92-64fe-4b53-9663-5c11b38a3051",
    "externalId": "inv-2025-0001",
    "filename": "invoice.pdf"
  },
  "data": {
    "extractions": [
      {
        "extractionType": "invoice_headers",
        "status": "success",
        "values": {
          "vendorName": {"value": "Acme Corp", "confidence": "high"},
          "invoiceNumber": {"value": "INV-001", "confidence": "high"},
          "totalAmount": {"value": 1250.00, "confidence": "high"}
        }
      }
    ]
  }
}

Quick Start

Create an HttpClient instance for API requests:

using System.Net.Http;

var baseUrl = Environment.GetEnvironmentVariable("GEMINA_BASE_URL")
    ?? "https://api.gemina.co";
var apiKey = Environment.GetEnvironmentVariable("GEMINA_API_KEY") ?? "";

var client = new HttpClient
{
    BaseAddress = new Uri(baseUrl),
    Timeout = TimeSpan.FromSeconds(90)
};
client.DefaultRequestHeaders.Add("X-API-Key", apiKey);

Authentication

All API requests require authentication via the X-API-Key header:

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your-api-key");

var response = await client.GetAsync(
    "https://api.gemina.co/api/v1/documents/"
);

Upload Document

Upload a document for extraction using multipart form data:

using var form = new MultipartFormDataContent();

form.Add(new StringContent("invoice_headers"), "extraction_types");
form.Add(new StringContent("invoice_line_items"), "extraction_types");
form.Add(new StringContent("inv-2025-0001"), "external_id");
form.Add(new StringContent("invictus"), "model_type");

var fileBytes = await File.ReadAllBytesAsync("invoice.pdf");
var fileContent = new ByteArrayContent(fileBytes);
fileContent.Headers.ContentType =
    new MediaTypeHeaderValue("application/pdf");
form.Add(fileContent, "file", "invoice.pdf");

var response = await client.PostAsync(
    "https://api.gemina.co/api/v1/documents/uploads",
    form
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Response Format

Successful extractions return structured JSON with field values and confidence scores:

{
  "status": "success",
  "meta": {
    "documentId": "9860df92-64fe-4b53-9663-5c11b38a3051",
    "externalId": "inv-2025-0001",
    "filename": "invoice.pdf"
  },
  "data": {
    "extractions": [
      {
        "extractionType": "invoice_headers",
        "status": "success",
        "values": {
          "vendorName": {"value": "Acme Corp", "confidence": "high"},
          "invoiceNumber": {"value": "INV-001", "confidence": "high"},
          "totalAmount": {"value": 1250.00, "confidence": "high"}
        }
      }
    ]
  }
}

Quick Start

Configure your API credentials:

<?php

define('GEMINA_BASE_URL', getenv('GEMINA_BASE_URL') ?: 'https://api.gemina.co');
define('GEMINA_API_KEY', getenv('GEMINA_API_KEY') ?: '');

if (empty(GEMINA_API_KEY)) {
    throw new Exception('Set GEMINA_API_KEY environment variable');
}

Authentication

All API requests require authentication via the X-API-Key header:

<?php

$ch = curl_init('https://api.gemina.co/api/v1/documents/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: your-api-key',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

Upload Document

Upload a document for extraction using cURL:

<?php

$url = 'https://api.gemina.co/api/v1/documents/uploads';
$cfile = new CURLFile('./invoice.pdf', 'application/pdf', 'invoice.pdf');

$postData = [
    'extraction_types[0]' => 'invoice_headers',
    'extraction_types[1]' => 'invoice_line_items',
    'external_id'         => 'inv-2025-0001',
    'model_type'          => 'invictus',
    'file'                => $cfile,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $postData,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: your-api-key',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Response Format

Successful extractions return structured JSON with field values and confidence scores:

{
  "status": "success",
  "meta": {
    "documentId": "9860df92-64fe-4b53-9663-5c11b38a3051",
    "externalId": "inv-2025-0001",
    "filename": "invoice.pdf"
  },
  "data": {
    "extractions": [
      {
        "extractionType": "invoice_headers",
        "status": "success",
        "values": {
          "vendorName": {"value": "Acme Corp", "confidence": "high"},
          "invoiceNumber": {"value": "INV-001", "confidence": "high"},
          "totalAmount": {"value": 1250.00, "confidence": "high"}
        }
      }
    ]
  }
}

API Reference

Extraction Types

invoice_headers - Invoice header fields
invoice_line_items - Line item details
ocr - Full text extraction
document_details_hebrew - Hebrew documents

Model Types

velox - Fast processing
praetorian - Balanced accuracy
invictus - Highest accuracy

Endpoints

POST /api/v1/documents/uploads
POST /api/v1/documents/uploads/web
GET /api/v1/documents/{id}
GET /api/v1/documents/results/{id}

Response Statuses

success - Extraction completed
pending - Job queued
in_process - Processing
failed - Error occurred

Ready to Get Started?

Start Free Trial Contact Sales

API Documentation

Getting Started

Quick Start

Authentication

Upload Document

Response Format

Quick Start

Authentication

Upload Document

Response Format

Quick Start

Authentication

Upload Document

Response Format

Quick Start

Authentication

Upload Document

Response Format

Quick Start

Authentication

Upload Document

Response Format

API Reference

Extraction Types

Model Types

Endpoints

Response Statuses

Ready to Get Started?