> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaledown.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Summarize

> Produce an abstractive summary of a block of text.

## Overview

The `/summarization/abstractive` endpoint condenses text in the model's own words without adding new information or commentary. Unlike extractive summarization, the output is a fluent rewrite - not a selection of lifted sentences.

## Request

<ParamField body="text" type="string">
  The input text to summarize. Can be an article, document, transcript, or any plain text string. Either `text` or `document` must be provided. If both are given, the OCR text is appended after `text`.
</ParamField>

<ParamField body="document" type="string">
  A base64-encoded file to summarize. Supported formats: JPEG, PNG, TIFF, single-page PDF, multi-page PDF. The file is processed via AWS Textract OCR and the extracted text is used as input. Either `text` or `document` must be provided.
</ParamField>

<ParamField body="document_mime_type" type="string">
  MIME type of the document (e.g. `"image/jpeg"`, `"application/pdf"`). Required when `document` is provided.
</ParamField>

<ParamField body="instructions" type="string">
  Optional additional rules for the summary. These are appended to the base instructions - they extend, not replace, the default behaviour (no new information, no commentary).

  Examples:

  * `"Use bullet points."`
  * `"Focus on financial figures only."`
  * `"Write in Spanish."`
  * `"Limit to 3 sentences."`
</ParamField>

<ParamField body="max_tokens" type="number" default={2048}>
  Maximum number of tokens in the generated summary.
</ParamField>

## Response

<ResponseField name="summary" type="string">
  The generated summary text.
</ResponseField>

<ResponseField name="input_chars" type="number">
  Character count of the input text.
</ResponseField>

<ResponseField name="output_chars" type="number">
  Character count of the generated summary.
</ResponseField>

<ResponseField name="latency_ms" type="number">
  End-to-end request latency in milliseconds.
</ResponseField>

<ResponseField name="ocr_text" type="string | null">
  The raw text extracted from the document via OCR. `null` if no `document` was provided.
</ResponseField>

## Error responses

| Status                      | Meaning                                                                        |
| --------------------------- | ------------------------------------------------------------------------------ |
| `422 Unprocessable Entity`  | Malformed request body, neither `text` nor `document` provided, or OCR failed. |
| `500 Internal Server Error` | Inference service unavailable.                                                 |
| `504 Gateway Timeout`       | Summarization request timed out.                                               |

## Authentication

Include your API key in every request using the `x-api-key` header.

```bash theme={null}
-H "x-api-key: <your-api-key>"
```

## Examples

### Basic summary

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.scaledown.xyz/summarization/abstractive \
    -H "Content-Type: application/json" \
    -H "x-api-key: <your-api-key>" \
    -d '{
      "text": "Your long text here..."
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.scaledown.xyz/summarization/abstractive",
      headers={"x-api-key": "<your-api-key>"},
      json={
          "text": "Your long text here...",
      },
  )
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.scaledown.xyz/summarization/abstractive",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "<your-api-key>",
      },
      body: JSON.stringify({
        text: "Your long text here...",
      }),
    }
  );
  const data = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "summary": "The company reported strong Q3 results, approved a share buyback program, and announced plans for Southeast Asian expansion.",
  "input_chars": 8340,
  "output_chars": 142,
  "latency_ms": 3241
}
```

### With instructions

Use `instructions` to control format, language, focus area, or length.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.scaledown.xyz/summarization/abstractive \
    -H "Content-Type: application/json" \
    -H "x-api-key: <your-api-key>" \
    -d '{
      "text": "Your long text here...",
      "instructions": "Use bullet points. Focus on dates and key decisions only.",
      "max_tokens": 500
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.scaledown.xyz/summarization/abstractive",
      headers={"x-api-key": "<your-api-key>"},
      json={
          "text": "Your long text here...",
          "instructions": "Use bullet points. Focus on dates and key decisions only.",
          "max_tokens": 500,
      },
  )
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.scaledown.xyz/summarization/abstractive",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "<your-api-key>",
      },
      body: JSON.stringify({
        text: "Your long text here...",
        instructions: "Use bullet points. Focus on dates and key decisions only.",
        max_tokens: 500,
      }),
    }
  );
  const data = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "summary": "- The company reported Q3 revenue of $4.2B, up 12% year-over-year.\n- The board approved a $500M share buyback program on October 14.\n- CEO announced plans to expand into Southeast Asia by mid-2027.",
  "input_chars": 8340,
  "output_chars": 198,
  "latency_ms": 3241
}
```

### Summarizing a document

Pass a base64-encoded image or PDF in the `document` field. The OCR text is extracted automatically and summarized. The raw OCR output is returned as `ocr_text`.

<CodeGroup>
  ```bash cURL theme={null}
  DOCUMENT=$(base64 -b 0 -i report.pdf)

  curl -X POST https://api.scaledown.xyz/summarization/abstractive \
    -H "Content-Type: application/json" \
    -H "x-api-key: <your-api-key>" \
    -d '{
      "document": "'"$DOCUMENT"'",
      "document_mime_type": "application/pdf",
      "instructions": "Use bullet points. Focus on key figures and decisions only."
    }'
  ```

  ```python Python theme={null}
  import base64
  import requests

  with open("report.pdf", "rb") as f:
      document = base64.b64encode(f.read()).decode()

  response = requests.post(
      "https://api.scaledown.xyz/summarization/abstractive",
      headers={"x-api-key": "<your-api-key>"},
      json={
          "document": document,
          "document_mime_type": "application/pdf",
          "instructions": "Use bullet points. Focus on key figures and decisions only.",
      },
  )
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  import fs from "fs";

  const document = fs.readFileSync("report.pdf").toString("base64");

  const response = await fetch(
    "https://api.scaledown.xyz/summarization/abstractive",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "<your-api-key>",
      },
      body: JSON.stringify({
        document,
        document_mime_type: "application/pdf",
        instructions: "Use bullet points. Focus on key figures and decisions only.",
      }),
    }
  );
  const data = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "summary": "- Q3 revenue reached $4.2B, up 12% year-over-year.\n- Board approved a $500M share buyback program.\n- CEO announced Southeast Asian expansion by mid-2027.",
  "input_chars": 12480,
  "output_chars": 178,
  "latency_ms": 4103,
  "ocr_text": "Q3 2024 Earnings Report\nRevenue: $4.2 billion (+12% YoY)\n..."
}
```

***

## Notes

* The base instructions (no new information, no commentary) are always applied. The `instructions` field adds on top of them - it does not replace them.
* Temperature, top-p, and other sampling parameters are fixed and not configurable via the API.


## OpenAPI

````yaml POST /summarization/abstractive
openapi: 3.1.0
info:
  title: ScaleDown API
  version: 1.0.0
servers:
  - url: https://api.scaledown.xyz
security:
  - apiKey: []
paths:
  /summarization/abstractive:
    post:
      summary: Summarize
      description: Produce an abstractive summary of a block of text.
      operationId: summarize
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                  description: The input text to summarize.
                instructions:
                  type: string
                  description: Optional additional rules for the summary.
                max_tokens:
                  type: number
                  default: 20048
                  description: Maximum number of tokens in the generated summary.
      responses:
        '200':
          description: Successful summarization
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: string
                  input_chars:
                    type: number
                  output_chars:
                    type: number
                  latency_ms:
                    type: number
        '400':
          description: Malformed request body or missing required fields.
        '401':
          description: Missing or invalid x-api-key.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Inference service unavailable.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````