Skip to content

Summarize

Provide an AI-generated summary of a document using semantic understanding.

Summary can be generated in any of the supported languages regardless of the language of the document.

Endpoint

POST /v20241104/summarize

API Request

  • Required Parameters

    document_id string required

    ID of the document to summarize.

    MinLength: 1   MaxLength: 128

    Optional Parameters

    language_summary string (enum)

    Language code (of a supported language) that indicates the language of the summary to return.

    Default is en.

    length_summary string (enum)

    Relative length of the summary to return.

    Default is short.

    Allowed values: short | medium | long

  • POST /v20241104/summarize

    curl -X POST "https://api.gainly.ai/v20241104/summarize" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \  # (1)!
  -d '{
    "document_id": "QrKSn5QBYzrcbYoh3NdH"
  }'
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    # Prompt for AI coding assistants/IDEs (e.g., ChatGPT, Claude, GitHub Copilot, Cursor, Windsurf)

Using the Gainly API:
1. Write code to call the summarize operation (see OpenAPI spec: https://api.gainly.ai/v20241104/openapi.json)
2. Implement authentication using the header "X-API-Key" as described in the docs: https://docs.gainly.ai/latest/api-reference/authentication/
3. Implement rate limit handling as described in the docs: https://docs.gainly.ai/latest/api-reference/rate-limits/
4. Implement error handling
5. Handle the response according to the SummarizeResults schema in the OpenAPI spec

    using System.Net.Http;
using System.Text.Json;
using System.Text;

var client = new HttpClient();

var url = "https://api.gainly.ai/v20241104/summarize";

var payload = new {
    document_id = "QrKSn5QBYzrcbYoh3NdH"
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY_HERE"); // (1)!

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.gainly.ai/v20241104/summarize"

    payload := map[string]interface{}{
        "document_id": "QrKSn5QBYzrcbYoh3NdH",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY_HERE") // (1)!

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

var client = HttpClient.newHttpClient();

var url = "https://api.gainly.ai/v20241104/summarize";

var payload = """
    {
        "document_id": "QrKSn5QBYzrcbYoh3NdH"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/json")
    .header("X-API-Key", "YOUR_API_KEY_HERE") // (1)!
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    const axios = require('axios');  // or: import axios from 'axios';

const url = 'https://api.gainly.ai/v20241104/summarize';

const payload = {
    document_id: 'QrKSn5QBYzrcbYoh3NdH'
};

const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE' // (1)!
};

axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.message));
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    <?php

$client = new \GuzzleHttp\Client();

$url = 'https://api.gainly.ai/v20241104/summarize';

$payload = [
    'document_id' => 'QrKSn5QBYzrcbYoh3NdH'
];

$response = $client->request('POST', $url, [
    'json' => $payload,
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-Key' => 'YOUR_API_KEY_HERE' # (1)!
    ],
]);

echo $response->getBody();
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    import requests

url = "https://api.gainly.ai/v20241104/summarize"

payload = {
    "document_id": "QrKSn5QBYzrcbYoh3NdH"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY_HERE" # (1)!
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    require 'json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI('https://api.gainly.ai/v20241104/summarize')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = 'YOUR_API_KEY_HERE' # (1)!
request.body = {
    document_id: 'QrKSn5QBYzrcbYoh3NdH'
}.to_json

response = http.request(request)
puts response.read_body
    1. Replace YOUR_API_KEY_HERE with the value of your API key.

API Response

{
    "object": "summarize_result",
    "url": "/v20241104/summarize",
    "data": [
        {
            "id": "QrKSn5QBYzrcbYoh3NdH",
            "title": "Cheetah Speed: The Science Behind the Fastest Land Animal",
            "summary": "The cheetah's speed reaches up to 60-70 mph due to a streamlined body, long limbs, and elastic spine. Key adaptations include semi-retractable claws for better traction and tough padded paws. Despite this, cheetahs rely heavily on quick hunts lasting only about 30 seconds; prolonged efforts lead to exhaustion.",
            "stop_reason": "end_turn",
            "source_uri": "/doc/cheetah-speed"
        }
    ],
    "document_id": "QrKSn5QBYzrcbYoh3NdH",
    "length_summary": "short",
    "language_summary": "en",
    "token_usage": {
        "semantic_tokens": 0,
        "llm_tokens": {
            "llm_output_tokens": 72,
            "llm_input_tokens": 876,
            "model": "model_2"
        }
    },
    "livemode": false
}

Summary

summary represents the AI-generated summary.

1
2
3
4
5
6
7
8
9
"data": [
    {
        "id": "QrKSn5QBYzrcbYoh3NdH",
        "title": "Cheetah Speed: The Science Behind the Fastest Land Animal",
        "summary": "The cheetah's speed reaches up to 60-70 mph due to a streamlined body, long limbs, and elastic spine. Key adaptations include semi-retractable claws for better traction and tough padded paws. Despite this, cheetahs rely heavily on quick hunts lasting only about 30 seconds; prolonged efforts lead to exhaustion.",
        "stop_reason": "end_turn",
        "source_uri": "/doc/cheetah-speed"
    }
],

Stop Reason

stop_reason indicates why the model stopped generating tokens.

  • end_turn: The model successfully completed generating the answer.
  • max_tokens: The model ran out of tokens, suggesting that you may need to adjust the value of length_summary parameter in your API request.
  • not_available: Reason is not available (rare cases).

Token Usage

token_usage indicates the number of tokens used to generate the summary.

"token_usage": {
    "semantic_tokens": 0,
    "llm_tokens": {
        "llm_output_tokens": 72,  // determined by the amount of text the LLM has to write
        "llm_input_tokens": 876,  // determined by the amount of text the LLM has to read
        "model": "model_2"
    }
}