{ "openapi": "3.0.3", "info": { "title": "Tuatara Summarize", "version": "1.0", "description": "Extractive summarization. Returns the document's own sentences, chosen by a vector-association model and cut to a sentence count, a ratio of the document or a token budget. Nothing is generated, so a summary cannot contain a fact that is not in the input. Typical use: shrink a long document before it reaches an expensive chat model. Zero data retention: request and response bodies are not stored. Benchmarks: https://cymetica.com/static/research/tuatara-summarize/README.md", "contact": {"name": "Cymetica", "url": "https://cymetica.com", "email": "contact@cymetica.com"}, "termsOfService": "https://cymetica.com/terms", "license": {"name": "Proprietary"} }, "servers": [{"url": "https://cymetica.com/api/v1/summarize/v1", "description": "Production (Japan)"}], "security": [{"bearer": []}, {"apiKey": []}], "tags": [ {"name": "Summarize", "description": "Summarize a document"}, {"name": "Account", "description": "Usage and service status"} ], "paths": { "/summarize": { "post": { "tags": ["Summarize"], "operationId": "summarize", "summary": "Summarize a document", "description": "Send the document as `text` (plain text or HTML). Choose the length with one of `sentence_count`, `ratio` or `max_tokens`; with none, two sentences are returned.", "requestBody": { "required": true, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/SummarizeRequest"}, "example": {"text": "The James Webb Space Telescope captured a new image of the Pillars of Creation. The pillars are columns of cool gas and dust. New stars are forming inside them. The image shows thousands of stars that earlier telescopes could not see.", "sentence_count": 2} }} }, "responses": { "200": {"description": "The summary", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Summary"}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "422": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "503": {"$ref": "#/components/responses/Error"} } } }, "/chat/completions": { "post": { "tags": ["Summarize"], "operationId": "chatCompletions", "summary": "OpenAI-compatible: summarize the last user message", "description": "Drop-in for OpenAI-style clients. The last user message is the document (or a JSON object with `text` and the parameters below). The assistant message is the summary. Streaming (`stream: true`) sends the summary as one chunk followed by usage.", "requestBody": { "required": true, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ChatRequest"}, "example": {"model": "tuatara-summarize-latest", "ratio": 0.2, "messages": [{"role": "user", "content": ""}]} }} }, "responses": { "200": {"description": "Chat completion whose message is the summary", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ChatCompletion"}}, "text/event-stream": {"schema": {"type": "string"}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/usage": { "get": { "tags": ["Account"], "operationId": "usage", "summary": "Requests and tokens used by this key", "parameters": [{"name": "days", "in": "query", "schema": {"type": "integer", "default": 30, "minimum": 1, "maximum": 90}}], "responses": {"200": {"description": "Usage by day", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"$ref": "#/components/responses/Error"}} } }, "/health": { "get": { "tags": ["Account"], "operationId": "health", "summary": "Service status and uptime", "security": [], "responses": {"200": {"description": "Status", "content": {"application/json": {"schema": {"type": "object", "properties": {"model": {"type": "string"}, "served": {"type": "boolean"}, "zero_data_retention": {"type": "boolean"}}}}}}} } }, "/models": { "get": { "tags": ["Account"], "operationId": "listModels", "summary": "Models, prices and limits", "security": [], "responses": {"200": {"description": "Model list", "content": {"application/json": {"schema": {"type": "object"}}}}} } } }, "components": { "securitySchemes": { "bearer": {"type": "http", "scheme": "bearer", "description": "Authorization: Bearer "}, "apiKey": {"type": "apiKey", "in": "header", "name": "X-Api-Key"} }, "responses": { "Error": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "RateLimited": {"description": "More than the key's requests a minute (300 by default); retry after the Retry-After seconds", "headers": {"Retry-After": {"schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "schemas": { "Params": { "type": "object", "properties": { "model": {"type": "string", "enum": ["tuatara-summarize-1.0", "tuatara-summarize-latest"], "default": "tuatara-summarize-latest"}, "sentence_count": {"type": "integer", "minimum": 1, "maximum": 500, "description": "Sentences to keep (1-5 in faithful mode)"}, "ratio": {"type": "number", "minimum": 0.05, "maximum": 0.9, "description": "Share of the document's sentences to keep"}, "max_tokens": {"type": "integer", "minimum": 1, "maximum": 200000, "description": "Token budget for the summary (cl100k tokens)"}, "context_control": {"type": "string", "maxLength": 64, "description": "One word that steers the summary toward a subject"}, "context_control_sensitivity_level": {"type": "number", "minimum": 0, "maximum": 10, "default": 2}, "mode": {"type": "string", "enum": ["auto", "faithful", "gs1", "gs2", "best", "tuned", "tuned-best"], "default": "auto", "description": "auto picks the best measured engine for the document's size; faithful is the original 2015 algorithm"}, "order": {"type": "string", "enum": ["document", "rank"], "default": "document", "description": "Sentences in document order, or best first"}, "output": {"type": "string", "enum": ["text", "json"], "default": "text", "description": "json adds the original v0.1 response shape"} } }, "SummarizeRequest": { "allOf": [ {"$ref": "#/components/schemas/Params"}, {"type": "object", "required": ["text"], "properties": {"text": {"type": "string", "description": "The document, plain text or HTML, up to 1.5 million characters / 200,000 tokens"}}} ] }, "ChatRequest": { "allOf": [ {"$ref": "#/components/schemas/Params"}, {"type": "object", "required": ["messages"], "properties": { "messages": {"type": "array", "items": {"type": "object", "properties": {"role": {"type": "string"}, "content": {"type": "string"}}}}, "stream": {"type": "boolean", "default": false} }} ] }, "Summary": { "type": "object", "properties": { "id": {"type": "string"}, "object": {"type": "string", "example": "summary"}, "created": {"type": "integer"}, "model": {"type": "string"}, "mode": {"type": "string", "description": "The engine that answered"}, "text": {"type": "string", "description": "The summary"}, "sentences": {"type": "array", "items": {"type": "object", "properties": {"index": {"type": "integer"}, "score": {"type": "number"}}}}, "keywords": {"type": "array", "items": {"type": "string"}}, "context_found": {"type": "boolean"}, "passthrough": {"type": "boolean", "description": "True when the document was already shorter than the request"}, "usage": {"type": "object", "properties": {"input_tokens": {"type": "integer"}, "output_tokens": {"type": "integer"}}} } }, "ChatCompletion": { "type": "object", "properties": { "id": {"type": "string"}, "object": {"type": "string", "example": "chat.completion"}, "model": {"type": "string"}, "choices": {"type": "array", "items": {"type": "object", "properties": {"index": {"type": "integer"}, "message": {"type": "object", "properties": {"role": {"type": "string"}, "content": {"type": "string"}}}, "finish_reason": {"type": "string"}}}}, "usage": {"type": "object", "properties": {"prompt_tokens": {"type": "integer"}, "completion_tokens": {"type": "integer"}, "total_tokens": {"type": "integer"}}} } }, "Error": { "type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}} } } } }