/summarization/abstractive endpoint. Start with the quick integration prompt to get something working fast, or use the production-ready prompt if you’re building for a live environment.
Prompts
Quick integration
Paste this prompt to generate a minimal Python function - useful for prototyping or one-off scripts.Quick integration prompt
Write a Python function `summarize_text(payload: dict, api_key: str,
instructions: str = None) -> str` that calls the ScaleDown abstractive
summarization API and returns the summary string.
API details:
- Endpoint: POST https://api.scaledown.xyz/summarization/abstractive
- Auth: HTTP header `x-api-key: <your key>`
- Request body (JSON):
{
"text": "<the document or passage to summarize>", // optional if document is provided
"document": "<base64-encoded file>", // optional; image or PDF
"document_mime_type": "image/jpeg", // required when document is set
"instructions": "<optional extra rules>", // optional field
"max_tokens": 20048 // optional field, default 20048
}
Either "text" or "document" must be provided. If both are given, OCR text is appended
after the plain text before summarization.
The "instructions" field is appended to the base faithful-summary behaviour -
it extends, not replaces, the default. Examples:
"Use bullet points."
"Focus on financial figures only."
"Write in Spanish."
"Limit to 3 sentences."
- Success response (JSON):
{
"summary": "<the generated summary>",
"input_chars": 8340,
"output_chars": 142,
"latency_ms": 3241,
"ocr_text": null // populated when a document was processed
}
- Error responses: 422 (malformed body, neither text nor document, or OCR failure),
500 (server error), 504 (timeout)
Requirements:
- The payload parameter is a dict that may contain "text", "document", and
"document_mime_type" keys. Pass it through to the request body.
- Accept the API key as the second parameter.
- Add "instructions" to the request body only if it is not None.
- Raise a ValueError with a descriptive message on any non-2xx HTTP response,
including the status code and response body in the message.
- Return the `summary` string on success.
Production-ready
Paste this prompt to generate a fully typed Python service class with error handling, retries, and environment-variable-based configuration.Production-ready prompt
Write a production-quality Python module for integrating the ScaleDown abstractive
summarization API.
API details:
- Endpoint: POST https://api.scaledown.xyz/summarization/abstractive
- Auth: HTTP header `x-api-key: <your key>`
- Request body (JSON):
{
"text": "<the document or passage to summarize>", // optional if document is provided
"document": "<base64-encoded file>", // optional; image or PDF
"document_mime_type": "application/pdf", // required when document is set
"instructions": "<optional rules appended to base behaviour>", // optional
"max_tokens": 20048 // optional, default 20048
}
Either "text" or "document" must be provided. If both are given, the OCR text is
appended after the plain text before summarization.
The "instructions" field extends (not replaces) the default faithful-summary
behaviour. It does not allow the model to add new information or commentary.
Example values: "Use bullet points.", "Focus on dates and key decisions only.",
"Write in Spanish.", "Limit to 3 sentences."
- Success response (JSON):
{
"summary": "<generated summary>",
"input_chars": 8340,
"output_chars": 142,
"latency_ms": 3241,
"ocr_text": "<raw OCR text>" | null // populated when a document was processed
}
- Error responses: 422 (malformed body, neither text nor document, or OCR failure),
500 (server error), 504 (timeout)
Apply these programming principles:
1. Environment configuration - Load the API key from the environment variable
SCALEDOWN_API_KEY. Raise a clear ValueError at construction time if it is missing
or empty, with a message that tells the developer exactly which variable to set.
2. Typed result - Define a SummaryResult dataclass with fields:
summary (str), input_chars (int), output_chars (int), latency_ms (int),
ocr_text (str | None)
3. Custom exception - Define a ScaleDownError exception class that carries
status_code (int) and message (str), and formats them into the exception message.
4. Single-responsibility client - Implement a ScaleDownSummarizer class with one
public method:
summarize(
text: str | None = None,
document: str | None = None,
document_mime_type: str | None = None,
instructions: str | None = None,
max_tokens: int | None = None
) -> SummaryResult
The class owns the requests.Session and sets the auth header once at __init__.
Omit optional fields from the request payload when they are None.
5. Retry with exponential backoff - Inside summarize(), on HTTP 5xx or 504 status,
wait 2 s before retry 1, 4 s before retry 2, 8 s before retry 3.
Raise ScaleDownError after all three retries are exhausted.
Raise ScaleDownError immediately on 422 (not retriable).
6. Type annotations - Add full type annotations to all functions, methods, and fields.
No module-level mutable state.
Async batch pipeline
Paste this prompt to generate an async batch summarizer that processes many documents concurrently with controlled parallelism.Async batch pipeline prompt
Write a Python async module that batch-summarizes a list of texts or documents using
the ScaleDown abstractive summarization API with controlled concurrency.
ScaleDown API details:
- Endpoint: POST https://api.scaledown.xyz/summarization/abstractive
- Auth: HTTP header `x-api-key: <your key>`
- Request body (JSON):
{
"text": "<the document or passage to summarize>", // optional if document is provided
"document": "<base64-encoded file>", // optional; image or PDF
"document_mime_type": "application/pdf", // required when document is set
"instructions": "<optional rules appended to base behaviour>", // optional
"max_tokens": 20048 // optional
}
Either "text" or "document" must be provided.
"instructions" extends, not replaces, the default faithful-summary behaviour.
- Success response (JSON):
{
"summary": str,
"input_chars": int,
"output_chars": int,
"latency_ms": int,
"ocr_text": str | None
}
- Error responses: 422 (bad body, neither text nor document, or OCR failure),
500 (server error), 504 (timeout)
Requirements:
1. Environment configuration - Load SCALEDOWN_API_KEY from os.environ at module load.
Raise ValueError with a clear message if the variable is absent or empty.
2. Input type - Define a SummarizeItem dataclass with fields:
text (str | None), document (str | None), document_mime_type (str | None)
At least one of text or document must be set per item.
3. Public async function:
batch_summarize(
items: list[SummarizeItem],
instructions: str | None = None,
max_tokens: int | None = None,
concurrency: int = 5
) -> list[str | None]
Returns summaries in the same order as the input list.
Returns None at an index if that document permanently fails after all retries.
4. Concurrency control - Use asyncio + aiohttp. Limit the number of simultaneous
in-flight requests with an asyncio.Semaphore initialized to the `concurrency`
argument.
5. Per-request retry with exponential backoff - For each individual request, retry
up to 3 times on HTTP 5xx or 504 status: wait 2 s, 4 s, 8 s before retries
1, 2, and 3. After 3 failures, store None for that index.
6. Logging - Log a WARNING via the `logging` module for each document that permanently
fails, including its index and the final error.
7. Omit optional fields - Do not include "instructions", "max_tokens", "document", or
"document_mime_type" in the request payload when they are None.
8. Entry point - Include an `if __name__ == "__main__":` block that calls
batch_summarize on a sample list of three SummarizeItem objects (text-only) and
prints each summary.
What the production prompt generates
The production-ready prompt instructs the AI to apply six programming principles. Here is an example of the code it produces:Principles encoded in the production-ready prompt: environment-variable config, typed result dataclass, custom exception class, single-responsibility service client, retry with exponential backoff, full type annotations.
Show Example output from the production-ready prompt
Show Example output from the production-ready prompt
import os
import time
import requests
from dataclasses import dataclass
from typing import Optional, Union
@dataclass
class SummaryResult:
summary: str
input_chars: int
output_chars: int
latency_ms: int
ocr_text: str | None
class ScaleDownError(Exception):
def __init__(self, status_code: int, message: str) -> None:
super().__init__(f"ScaleDown API error {status_code}: {message}")
self.status_code = status_code
self.message = message
class ScaleDownSummarizer:
BASE_URL = "https://api.scaledown.xyz/summarization/abstractive"
def __init__(self) -> None:
api_key = os.environ.get("SCALEDOWN_API_KEY")
if not api_key:
raise ValueError(
"SCALEDOWN_API_KEY environment variable is missing or empty. "
"Set it with: export SCALEDOWN_API_KEY=your_key_here"
)
self._session = requests.Session()
self._session.headers.update({"x-api-key": api_key})
def summarize(
self,
text: str | None = None,
document: str | None = None,
document_mime_type: str | None = None,
instructions: Optional[str] = None,
max_tokens: Optional[int] = None,
) -> SummaryResult:
payload: dict = {}
if text is not None:
payload["text"] = text
if document is not None:
payload["document"] = document
if document_mime_type is not None:
payload["document_mime_type"] = document_mime_type
if instructions is not None:
payload["instructions"] = instructions
if max_tokens is not None:
payload["max_tokens"] = max_tokens
retry_delays = [2, 4, 8]
last_error: Optional[ScaleDownError] = None
for attempt in range(len(retry_delays) + 1):
if attempt > 0:
time.sleep(retry_delays[attempt - 1])
response = self._session.post(self.BASE_URL, json=payload)
if response.ok:
data = response.json()
return SummaryResult(
summary=data["summary"],
input_chars=data["input_chars"],
output_chars=data["output_chars"],
latency_ms=data["latency_ms"],
ocr_text=data.get("ocr_text"),
)
if response.status_code in {500, 502, 503, 504}:
last_error = ScaleDownError(response.status_code, response.text)
continue # retry
# 422: not retriable
raise ScaleDownError(response.status_code, response.text)
raise last_error # type: ignore[misc]
import os
os.environ["SCALEDOWN_API_KEY"] = "your_key_here"
summarizer = ScaleDownSummarizer()
result = summarizer.summarize(
text="The company reported Q3 revenue of $4.2B, up 12% year-over-year...",
instructions="Use bullet points. Focus on dates and key decisions only.",
)
print(result.summary)
print(f"Compressed {result.input_chars} chars to {result.output_chars} chars")
# result.ocr_text is None when no document was provided