> This page is for version v2 API (default). > For other versions, use one of these documentation indexes: > - v2 API (default): https://docs.cohere.com/v2/llms.txt > - v1 API: https://docs.cohere.com/v1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.cohere.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cohere.com/_mcp/server. # Summarize POST https://api.cohere.com/v1/summarize Content-Type: application/json This API is marked as "Legacy" and is no longer maintained. Follow the [migration guide](https://docs.cohere.com/docs/migrating-from-cogenerate-to-cochat) to start using the Chat API. Generates a summary in English for a given text. Reference: https://docs.cohere.com/reference/summarize ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `X-Client-Name` (string, optional) — The name of the project that is making the request. ### Body (application/json) This endpoint expects an object. - `text` (string, required) — The text to generate a summary for. Can be up to 100,000 characters long. Currently the only supported language is English. - `length` (enum, optional, default: medium) — One of `short`, `medium`, `long`, or `auto` defaults to `auto`. Indicates the approximate length of the summary. If `auto` is selected, the best option will be picked based on the input text. - Allowed values: `short`, `medium`, `long` - `format` (enum, optional, default: paragraph) — One of `paragraph`, `bullets`, or `auto`, defaults to `auto`. Indicates the style in which the summary will be delivered - in a free form paragraph or in bullet points. If `auto` is selected, the best option will be picked based on the input text. - Allowed values: `paragraph`, `bullets` - `model` (string, optional) — The identifier of the model to generate the summary with. Currently available models are `command` (default), `command-nightly` (experimental), `command-light`, and `command-light-nightly` (experimental). Smaller, "light" models are faster, while larger models will perform better. - `extractiveness` (enum, optional, default: low) — One of `low`, `medium`, `high`, or `auto`, defaults to `auto`. Controls how close to the original text the summary is. `high` extractiveness summaries will lean towards reusing sentences verbatim, while `low` extractiveness summaries will tend to paraphrase more. If `auto` is selected, the best option will be picked based on the input text. - Allowed values: `low`, `medium`, `high` - `temperature` (double, optional, default: 0.3) — Ranges from 0 to 5. Controls the randomness of the output. Lower values tend to generate more “predictable” output, while higher values tend to generate more “creative” output. The sweet spot is typically between 0 and 1. - `additional_command` (string, optional) — A free-form instruction for modifying how the summaries get generated. Should complete the sentence "Generate a summary _". Eg. "focusing on the next steps" or "written by Yoda" ## Response ### 200 OK - `id` (string, optional) — Generated ID for the summary - `summary` (string, optional) — Generated summary for the text - `meta` (ApiMeta, optional) ## Errors ### 400 Bad Request Error This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields - `message` (string, optional) - `id` (string, optional) ### 401 Unauthorized Error This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions - `message` (string, optional) - `id` (string, optional) ### 403 Forbidden Error This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions - `message` (string, optional) - `id` (string, optional) ### 404 Not Found Error This error is returned when a resource is not found. This could be because: - The endpoint does not exist - The resource does not exist eg model id, dataset id - `message` (string, optional) - `id` (string, optional) ### 422 Unprocessable Entity Error This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields - `message` (string, optional) - `id` (string, optional) ### 429 Too Many Requests Error Too many requests - `message` (string, optional) - `id` (string, optional) ### 498 Invalid Token Error This error is returned when a request or response contains a deny-listed token. - `message` (string, optional) - `id` (string, optional) ### 499 Client Closed Request Error This error is returned when a request is cancelled by the user. - `message` (string, optional) - `id` (string, optional) ### 500 Internal Server Error This error is returned when an uncategorised internal server error occurs. - `message` (string, optional) - `id` (string, optional) ### 501 Not Implemented Error This error is returned when the requested feature is not implemented. - `message` (string, optional) - `id` (string, optional) ### 503 Service Unavailable Error This error is returned when the service is unavailable. This could be due to: - Too many users trying to access the service at the same time - `message` (string, optional) - `id` (string, optional) ### 504 Gateway Timeout Error This error is returned when a request to the server times out. This could be due to: - An internal services taking too long to respond - `message` (string, optional) - `id` (string, optional) ## Types ### ApiMeta - `api_version` (ApiMetaApiVersion, optional) - `billed_units` (ApiMetaBilledUnits, optional) - `tokens` (ApiMetaTokens, optional) - `cached_tokens` (double, optional) — The number of prompt tokens that hit the inference cache. - `warnings` (list of string, optional) ### ApiMetaApiVersion - `version` (string, required) - `is_deprecated` (boolean, optional) - `is_experimental` (boolean, optional) ### ApiMetaBilledUnits - `images` (double, optional) — The number of billed images. - `input_tokens` (double, optional) — The number of billed input tokens. - `image_tokens` (double, optional) — The number of billed image tokens. - `output_tokens` (double, optional) — The number of billed output tokens. - `search_units` (double, optional) — The number of billed search units. - `classifications` (double, optional) — The number of billed classifications units. - `pages` (double, optional) — The number of billed pages parsed. ### ApiMetaTokens - `input_tokens` (double, optional) — The number of tokens used as input to the model. - `output_tokens` (double, optional) — The number of tokens produced by the model. ## Examples **Request** ```json { "text": "Ice cream is a sweetened frozen food typically eaten as a snack or dessert. It may be made from milk or cream and is flavoured with a sweetener, either sugar or an alternative, and a spice, such as cocoa or vanilla, or with fruit such as strawberries or peaches. It can also be made by whisking a flavored cream base and liquid nitrogen together. Food coloring is sometimes added, in addition to stabilizers. The mixture is cooled below the freezing point of water and stirred to incorporate air spaces and to prevent detectable ice crystals from forming. The result is a smooth, semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). It becomes more malleable as its temperature increases.\n\nThe meaning of the name \"ice cream\" varies from one country to another. In some countries, such as the United States, \"ice cream\" applies only to a specific variety, and most governments regulate the commercial use of the various terms according to the relative quantities of the main ingredients, notably the amount of cream. Products that do not meet the criteria to be called ice cream are sometimes labelled \"frozen dairy dessert\" instead. In other countries, such as Italy and Argentina, one word is used fo\r all variants. Analogues made from dairy alternatives, such as goat's or sheep's milk, or milk substitutes (e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are lactose intolerant, allergic to dairy protein or vegan." } ``` **Response** ```json { "id": "aa0b828e-f9cf-484d-a84d-cb62f556e841", "summary": "Ice cream is a frozen dessert made by whipping a cream base and liquid nitrogen together. It is then flavoured with sweeteners, spices and fruits. Ice cream can also be made using alternative milks, such as soy or almond, for those who are lactose intolerant or vegan.", "meta": { "api_version": { "version": "1" }, "billed_units": { "input_tokens": 321, "output_tokens": 55 } } } ``` **SDK Code** ```go Cohere Go SDK package main import ( "context" "log" "os" cohere "github.com/cohere-ai/cohere-go/v2" client "github.com/cohere-ai/cohere-go/v2/client" ) func main() { co := client.NewClient(client.WithToken(os.Getenv("CO_API_KEY"))) resp, err := co.Summarize( context.TODO(), &cohere.SummarizeRequest{ Text: "the quick brown fox jumped over the lazy dog and then the dog jumped over the fox the quick brown fox jumped over the lazy dog the quick brown fox jumped over the lazy dog the quick brown fox jumped over the lazy dog the quick brown fox jumped over the lazy dog", }, ) if err != nil { log.Fatal(err) } log.Printf("%+v", resp) } ``` ```typescript Cohere TypeScript SDK import { CohereClient } from 'cohere-ai'; const cohere = new CohereClient({}); (async () => { const summarize = await cohere.summarize({ text: 'Ice cream is a sweetened frozen food typically eaten as a snack or dessert. ' + 'It may be made from milk or cream and is flavoured with a sweetener, ' + 'either sugar or an alternative, and a spice, such as cocoa or vanilla, ' + 'or with fruit such as strawberries or peaches. ' + 'It can also be made by whisking a flavored cream base and liquid nitrogen together. ' + 'Food coloring is sometimes added, in addition to stabilizers. ' + 'The mixture is cooled below the freezing point of water and stirred to incorporate air spaces ' + 'and to prevent detectable ice crystals from forming. The result is a smooth, ' + 'semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). ' + 'It becomes more malleable as its temperature increases.\n\n' + 'The meaning of the name "ice cream" varies from one country to another. ' + 'In some countries, such as the United States, "ice cream" applies only to a specific variety, ' + 'and most governments regulate the commercial use of the various terms according to the ' + 'relative quantities of the main ingredients, notably the amount of cream. ' + 'Products that do not meet the criteria to be called ice cream are sometimes labelled ' + '"frozen dairy dessert" instead. In other countries, such as Italy and Argentina, ' + 'one word is used fo\r all variants. Analogues made from dairy alternatives, ' + "such as goat's or sheep's milk, or milk substitutes " + '(e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are ' + 'lactose intolerant, allergic to dairy protein or vegan.', }); console.log(summarize); })(); ``` ```python Sync import cohere co = cohere.Client() text = ( "Ice cream is a sweetened frozen food typically eaten as a snack or dessert. " "It may be made from milk or cream and is flavoured with a sweetener, " "either sugar or an alternative, and a spice, such as cocoa or vanilla, " "or with fruit such as strawberries or peaches. " "It can also be made by whisking a flavored cream base and liquid nitrogen together. " "Food coloring is sometimes added, in addition to stabilizers. " "The mixture is cooled below the freezing point of water and stirred to incorporate air spaces " "and to prevent detectable ice crystals from forming. The result is a smooth, " "semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). " "It becomes more malleable as its temperature increases.\n\n" 'The meaning of the name "ice cream" varies from one country to another. ' 'In some countries, such as the United States, "ice cream" applies only to a specific variety, ' "and most governments regulate the commercial use of the various terms according to the " "relative quantities of the main ingredients, notably the amount of cream. " "Products that do not meet the criteria to be called ice cream are sometimes labelled " '"frozen dairy dessert" instead. In other countries, such as Italy and Argentina, ' "one word is used fo\r all variants. Analogues made from dairy alternatives, " "such as goat's or sheep's milk, or milk substitutes " "(e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are " "lactose intolerant, allergic to dairy protein or vegan." ) response = co.summarize( text=text, ) print(response) ``` ```python Async import cohere import asyncio co = cohere.AsyncClient() text = ( "Ice cream is a sweetened frozen food typically eaten as a snack or dessert. " "It may be made from milk or cream and is flavoured with a sweetener, " "either sugar or an alternative, and a spice, such as cocoa or vanilla, " "or with fruit such as strawberries or peaches. " "It can also be made by whisking a flavored cream base and liquid nitrogen together. " "Food coloring is sometimes added, in addition to stabilizers. " "The mixture is cooled below the freezing point of water and stirred to incorporate air spaces " "and to prevent detectable ice crystals from forming. The result is a smooth, " "semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). " "It becomes more malleable as its temperature increases.\n\n" 'The meaning of the name "ice cream" varies from one country to another. ' 'In some countries, such as the United States, "ice cream" applies only to a specific variety, ' "and most governments regulate the commercial use of the various terms according to the " "relative quantities of the main ingredients, notably the amount of cream. " "Products that do not meet the criteria to be called ice cream are sometimes labelled " '"frozen dairy dessert" instead. In other countries, such as Italy and Argentina, ' "one word is used fo\r all variants. Analogues made from dairy alternatives, " "such as goat's or sheep's milk, or milk substitutes " "(e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are " "lactose intolerant, allergic to dairy protein or vegan." ) async def main(): response = await co.summarize( text=text, ) print(response) asyncio.run(main()) ``` ```java Cohere java SDK /* (C)2024 */ import com.cohere.api.Cohere; import com.cohere.api.requests.SummarizeRequest; import com.cohere.api.types.SummarizeResponse; public class SummarizePost { public static void main(String[] args) { Cohere cohere = Cohere.builder().clientName("snippet").build(); SummarizeResponse response = cohere.summarize( SummarizeRequest.builder() .text( """ Ice cream is a sweetened frozen food typically eaten as a snack or dessert.\s It may be made from milk or cream and is flavoured with a sweetener,\s either sugar or an alternative, and a spice, such as cocoa or vanilla,\s or with fruit such as strawberries or peaches.\s It can also be made by whisking a flavored cream base and liquid nitrogen together.\s Food coloring is sometimes added, in addition to stabilizers.\s The mixture is cooled below the freezing point of water and stirred to incorporate air spaces\s and to prevent detectable ice crystals from forming. The result is a smooth,\s semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F).\s It becomes more malleable as its temperature increases.\\n\\n The meaning of the name "ice cream" varies from one country to another.\s In some countries, such as the United States, "ice cream" applies only to a specific variety,\s and most governments regulate the commercial use of the various terms according to the\s relative quantities of the main ingredients, notably the amount of cream.\s Products that do not meet the criteria to be called ice cream are sometimes labelled\s "frozen dairy dessert" instead. In other countries, such as Italy and Argentina,\s one word is used fo\\r all variants. Analogues made from dairy alternatives,\s such as goat's or sheep's milk, or milk substitutes\s (e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are\s lactose intolerant, allergic to dairy protein or vegan. """) .build()); System.out.println(response); } } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.cohere.com/v1/summarize") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"text\": \"Ice cream is a sweetened frozen food typically eaten as a snack or dessert. It may be made from milk or cream and is flavoured with a sweetener, either sugar or an alternative, and a spice, such as cocoa or vanilla, or with fruit such as strawberries or peaches. It can also be made by whisking a flavored cream base and liquid nitrogen together. Food coloring is sometimes added, in addition to stabilizers. The mixture is cooled below the freezing point of water and stirred to incorporate air spaces and to prevent detectable ice crystals from forming. The result is a smooth, semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). It becomes more malleable as its temperature increases.\\n\\nThe meaning of the name \\\"ice cream\\\" varies from one country to another. In some countries, such as the United States, \\\"ice cream\\\" applies only to a specific variety, and most governments regulate the commercial use of the various terms according to the relative quantities of the main ingredients, notably the amount of cream. Products that do not meet the criteria to be called ice cream are sometimes labelled \\\"frozen dairy dessert\\\" instead. In other countries, such as Italy and Argentina, one word is used fo\\r all variants. Analogues made from dairy alternatives, such as goat's or sheep's milk, or milk substitutes (e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are lactose intolerant, allergic to dairy protein or vegan.\"\n}" response = http.request(request) puts response.read_body ``` ```php request('POST', 'https://api.cohere.com/v1/summarize', [ 'body' => '{ "text": "Ice cream is a sweetened frozen food typically eaten as a snack or dessert. It may be made from milk or cream and is flavoured with a sweetener, either sugar or an alternative, and a spice, such as cocoa or vanilla, or with fruit such as strawberries or peaches. It can also be made by whisking a flavored cream base and liquid nitrogen together. Food coloring is sometimes added, in addition to stabilizers. The mixture is cooled below the freezing point of water and stirred to incorporate air spaces and to prevent detectable ice crystals from forming. The result is a smooth, semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). It becomes more malleable as its temperature increases.\\n\\nThe meaning of the name \\"ice cream\\" varies from one country to another. In some countries, such as the United States, \\"ice cream\\" applies only to a specific variety, and most governments regulate the commercial use of the various terms according to the relative quantities of the main ingredients, notably the amount of cream. Products that do not meet the criteria to be called ice cream are sometimes labelled \\"frozen dairy dessert\\" instead. In other countries, such as Italy and Argentina, one word is used fo\\r all variants. Analogues made from dairy alternatives, such as goat\'s or sheep\'s milk, or milk substitutes (e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are lactose intolerant, allergic to dairy protein or vegan." }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.cohere.com/v1/summarize"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"text\": \"Ice cream is a sweetened frozen food typically eaten as a snack or dessert. It may be made from milk or cream and is flavoured with a sweetener, either sugar or an alternative, and a spice, such as cocoa or vanilla, or with fruit such as strawberries or peaches. It can also be made by whisking a flavored cream base and liquid nitrogen together. Food coloring is sometimes added, in addition to stabilizers. The mixture is cooled below the freezing point of water and stirred to incorporate air spaces and to prevent detectable ice crystals from forming. The result is a smooth, semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). It becomes more malleable as its temperature increases.\\n\\nThe meaning of the name \\\"ice cream\\\" varies from one country to another. In some countries, such as the United States, \\\"ice cream\\\" applies only to a specific variety, and most governments regulate the commercial use of the various terms according to the relative quantities of the main ingredients, notably the amount of cream. Products that do not meet the criteria to be called ice cream are sometimes labelled \\\"frozen dairy dessert\\\" instead. In other countries, such as Italy and Argentina, one word is used fo\\r all variants. Analogues made from dairy alternatives, such as goat's or sheep's milk, or milk substitutes (e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are lactose intolerant, allergic to dairy protein or vegan.\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["text": "Ice cream is a sweetened frozen food typically eaten as a snack or dessert. It may be made from milk or cream and is flavoured with a sweetener, either sugar or an alternative, and a spice, such as cocoa or vanilla, or with fruit such as strawberries or peaches. It can also be made by whisking a flavored cream base and liquid nitrogen together. Food coloring is sometimes added, in addition to stabilizers. The mixture is cooled below the freezing point of water and stirred to incorporate air spaces and to prevent detectable ice crystals from forming. The result is a smooth, semi-solid foam that is solid at very low temperatures (below 2 °C or 35 °F). It becomes more malleable as its temperature increases. The meaning of the name \"ice cream\" varies from one country to another. In some countries, such as the United States, \"ice cream\" applies only to a specific variety, and most governments regulate the commercial use of the various terms according to the relative quantities of the main ingredients, notably the amount of cream. Products that do not meet the criteria to be called ice cream are sometimes labelled \"frozen dairy dessert\" instead. In other countries, such as Italy and Argentina, one word is used fo all variants. Analogues made from dairy alternatives, such as goat's or sheep's milk, or milk substitutes (e.g., soy, cashew, coconut, almond milk or tofu), are available for those who are lactose intolerant, allergic to dairy protein or vegan."] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.cohere.com/v1/summarize")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```