Generate

POST/v1/generateGenerate

<Warning> This API is marked as "Legacy" and is no longer maintained. Follow the migration guide to start using the Chat API. </Warning> Generates realistic text conditioned on a given input.

Parameters

X-Client-Namestringheader

The name of the project that is making the request.

Request body

application/json

objectwrite only

end_sequencesarray of string

The generated text will be cut at the beginning of the earliest occurrence of an end sequence. The sequence will be excluded from the text.

Show child attributes

frequency_penaltynumber

Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation. Using `frequency_penalty` in combination with `presence_penalty` is not supported on newer models.

kinteger

Ensures only the top `k` most likely tokens are considered for generation at each step. Defaults to `0`, min value of `0`, max value of `500`.

max_tokensinteger

The maximum number of tokens the model will generate as part of the response. Note: Setting a low value may result in incomplete generations. This parameter is off by default, and if it's not specified, the model will continue generating until it emits an EOS completion token. See [BPE Tokens](/bpe-tokens-wiki) for more details. Can only be set to `0` if `return_likelihoods` is set to `ALL` to get the likelihood of the prompt.

modelstring

The identifier of the model to generate 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. [Custom models](https://docs.cohere.com/docs/training-custom-models) can also be supplied with their full ID.

num_generationsinteger

The maximum number of generations that will be returned. Defaults to `1`, min value of `1`, max value of `5`.

pnumber

Ensures that only the most likely tokens, with total probability mass of `p`, are considered for generation at each step. If both `k` and `p` are enabled, `p` acts after `k`. Defaults to `0.75`. min value of `0.01`, max value of `0.99`.

presence_penaltynumber

Defaults to `0.0`, min value of `0.0`, max value of `1.0`. Can be used to reduce repetitiveness of generated tokens. Similar to `frequency_penalty`, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies. Using `frequency_penalty` in combination with `presence_penalty` is not supported on newer models.

presetstring

Identifier of a custom preset. A preset is a combination of parameters, such as prompt, temperature etc. You can create presets in the [playground](https://dashboard.cohere.com/playground/generate). When a preset is specified, the `prompt` parameter becomes optional, and any included parameters will override the preset's parameters.

promptstringrequired

The input text that serves as the starting point for generating the response. Note: The prompt will be pre-processed and modified before reaching the model.

raw_promptingboolean

When enabled, the user's prompt will be sent to the model without any pre-processing.

return_likelihoodsstring

One of `GENERATION|NONE` to specify how and if the token likelihoods are returned with the response. Defaults to `NONE`. If `GENERATION` is selected, the token likelihoods will only be provided for generated text. WARNING: `ALL` is deprecated, and will be removed in a future release.

one of "GENERATION", "ALL", "NONE" · default "NONE"

seedinteger

If specified, the backend will make a best effort to sample tokens deterministically, such that repeated requests with the same seed and parameters should return the same result. However, determinism cannot be totally guaranteed. Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments

minimum 0

stop_sequencesarray of string

The generated text will be cut at the end of the earliest occurrence of a stop sequence. The sequence will be included the text.

Show child attributes

streamboolean

When `true`, the response will be a JSON stream of events. Streaming is beneficial for user interfaces that render the contents of the response piece by piece, as it gets generated. The final event will contain the complete response, and will contain an `is_finished` field set to `true`. The event will also contain a `finish_reason`, which can be one of the following: - `COMPLETE` - the model sent back a finished reply - `MAX_TOKENS` - the reply was cut off because the model reached the maximum number of tokens for its context length - `ERROR` - something went wrong when generating the reply - `ERROR_TOXIC` - the model generated a reply that was deemed toxic

temperaturenumber

A non-negative float that tunes the degree of randomness in generation. Lower temperatures mean less random generations. See [Temperature](/temperature-wiki) for more details. Defaults to `0.75`, min value of `0.0`, max value of `5.0`.

truncatestring

One of `NONE|START|END` to specify how the API will handle inputs longer than the maximum token length. Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model. If `NONE` is selected, when the input exceeds the maximum input token length an error will be returned.

one of "NONE", "START", "END" · default "END"

Example request

{
  "end_sequences": [
    "string"
  ],
  "frequency_penalty": 0,
  "k": 0,
  "max_tokens": 0,
  "model": "string",
  "num_generations": 0,
  "p": 0,
  "presence_penalty": 0,
  "preset": "my-preset-a58sbd",
  "prompt": "Please explain to me how LLMs work",
  "raw_prompting": true,
  "return_likelihoods": "NONE",
  "seed": 0,
  "stop_sequences": [
    "string"
  ],
  "stream": true,
  "temperature": 0,
  "truncate": "END"
}

Responses

Headers

X-API-Warning

The name of the project that is making the request.

objectGeneration

generationsarray of objectrequired

List of generated results

Show child attributes

Show array items

idstringrequired

indexinteger

Refers to the nth generation. Only present when `num_generations` is greater than zero.

likelihoodnumber

textstringrequired

token_likelihoodsarray of object

Only returned if `return_likelihoods` is set to `GENERATION` or `ALL`. The likelihood refers to the average log-likelihood of the entire specified string, which is useful for [evaluating the performance of your model](likelihood-eval), especially if you've created a [custom model](https://docs.cohere.com/docs/training-custom-models). Individual token likelihoods provide the log-likelihood of each token. The first token will not have a likelihood.

Show child attributes

Show array items

likelihoodnumberrequired

tokenstringrequired

idstringrequired

metaobject

Show child attributes

api_versionobject

Show child attributes

is_deprecatedboolean

is_experimentalboolean

versionstringrequired

billed_unitsobject

Show child attributes

classificationsnumber

The number of billed classifications units.

image_tokensnumber

The number of billed image tokens.

imagesnumber

The number of billed images.

input_tokensnumber

The number of billed input tokens.

output_tokensnumber

The number of billed output tokens.

pagesnumber

The number of billed pages parsed.

search_unitsnumber

The number of billed search units.

cached_tokensnumber

The number of prompt tokens that hit the inference cache.

tokensobject

Show child attributes

input_tokensnumber

The number of tokens used as input to the model.

output_tokensnumber

The number of tokens produced by the model.

warningsarray of string

Show child attributes

promptstring

Prompt used for generations.

valueGenerateStreamedResponse

Response in content type stream when `stream` is `true` in the request parameters. Generation tokens are streamed with the GenerationStream response. The final response is of type GenerationFinalResponse.

oneOf · 3 options

Option 1valueGenerateStreamText

allOf · 2 options

Option 1objectGenerateStreamEvent

event_typestringrequired

one of "text-generation", "stream-end", "stream-error"

Option 2object

indexinteger

Refers to the nth generation. Only present when `num_generations` is greater than zero, and only when text responses are being streamed.

is_finishedbooleanrequired

textstringrequired

A segment of text of the generation.

Option 2valueGenerateStreamEnd

allOf · 2 options

Option 1: GenerateStreamEvent ↑

Option 2object

finish_reasonstring

one of "COMPLETE", "STOP_SEQUENCE", "ERROR", "ERROR_TOXIC", "ERROR_LIMIT", "USER_CANCEL", "MAX_TOKENS", "TIMEOUT"

is_finishedbooleanrequired

responseobjectrequired

Show child attributes

generationsarray of object

Show child attributes

Show array items

finish_reasonstringrequired

one of "COMPLETE", "STOP_SEQUENCE", "ERROR", "ERROR_TOXIC", "ERROR_LIMIT", "USER_CANCEL", "MAX_TOKENS", "TIMEOUT"

idstringrequired

indexinteger

Refers to the nth generation. Only present when `num_generations` is greater than zero.

textstringrequired

Full text of the generation.

idstringrequired

promptstring

Option 3valueGenerateStreamError

allOf · 2 options

Option 1: GenerateStreamEvent ↑

Option 2object

errstringrequired

Error message

finish_reasonstringrequired

one of "COMPLETE", "STOP_SEQUENCE", "ERROR", "ERROR_TOXIC", "ERROR_LIMIT", "USER_CANCEL", "MAX_TOKENS", "TIMEOUT"

indexinteger

Refers to the nth generation. Only present when `num_generations` is greater than zero.

is_finishedbooleanrequired

Example response

{
  "generations": [
    {
      "id": "string",
      "index": 0,
      "likelihood": 0,
      "text": "string",
      "token_likelihoods": [
        {
          "likelihood": 0,
          "token": "string"
        }
      ]
    }
  ],
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "prompt": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

Examples

X-Client-Nameheader parameter

curl -X POST 'https://api.cohere.com/v1/generate' \
  -H 'Content-Type: application/json' \
  -d '{"end_sequences":["string"],"frequency_penalty":0,"k":0,"max_tokens":0,"model":"string","num_generations":0,"p":0,"presence_penalty":0,"preset":"my-preset-a58sbd","prompt":"Please explain to me how LLMs work","raw_prompting":true,"return_likelihoods":"NONE","seed":0,"stop_sequences":["string"],"stream":true,"temperature":0,"truncate":"END"}'

const response = await fetch('https://api.cohere.com/v1/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"end_sequences":["string"],"frequency_penalty":0,"k":0,"max_tokens":0,"model":"string","num_generations":0,"p":0,"presence_penalty":0,"preset":"my-preset-a58sbd","prompt":"Please explain to me how LLMs work","raw_prompting":true,"return_likelihoods":"NONE","seed":0,"stop_sequences":["string"],"stream":true,"temperature":0,"truncate":"END"}),
});
const data = await response.json();

const response = await fetch('https://api.cohere.com/v1/generate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"end_sequences\":[\"string\"],\"frequency_penalty\":0,\"k\":0,\"max_tokens\":0,\"model\":\"string\",\"num_generations\":0,\"p\":0,\"presence_penalty\":0,\"preset\":\"my-preset-a58sbd\",\"prompt\":\"Please explain to me how LLMs work\",\"raw_prompting\":true,\"return_likelihoods\":\"NONE\",\"seed\":0,\"stop_sequences\":[\"string\"],\"stream\":true,\"temperature\":0,\"truncate\":\"END\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.cohere.com/v1/generate",
    headers={"Content-Type": "application/json"},
    data='{"end_sequences":["string"],"frequency_penalty":0,"k":0,"max_tokens":0,"model":"string","num_generations":0,"p":0,"presence_penalty":0,"preset":"my-preset-a58sbd","prompt":"Please explain to me how LLMs work","raw_prompting":true,"return_likelihoods":"NONE","seed":0,"stop_sequences":["string"],"stream":true,"temperature":0,"truncate":"END"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"end_sequences":["string"],"frequency_penalty":0,"k":0,"max_tokens":0,"model":"string","num_generations":0,"p":0,"presence_penalty":0,"preset":"my-preset-a58sbd","prompt":"Please explain to me how LLMs work","raw_prompting":true,"return_likelihoods":"NONE","seed":0,"stop_sequences":["string"],"stream":true,"temperature":0,"truncate":"END"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.cohere.com/v1/generate", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.cohere.com/v1/generate");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"end_sequences\":[\"string\"],\"frequency_penalty\":0,\"k\":0,\"max_tokens\":0,\"model\":\"string\",\"num_generations\":0,\"p\":0,\"presence_penalty\":0,\"preset\":\"my-preset-a58sbd\",\"prompt\":\"Please explain to me how LLMs work\",\"raw_prompting\":true,\"return_likelihoods\":\"NONE\",\"seed\":0,\"stop_sequences\":[\"string\"],\"stream\":true,\"temperature\":0,\"truncate\":\"END\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.cohere.com/v1/generate"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"end_sequences\":[\"string\"],\"frequency_penalty\":0,\"k\":0,\"max_tokens\":0,\"model\":\"string\",\"num_generations\":0,\"p\":0,\"presence_penalty\":0,\"preset\":\"my-preset-a58sbd\",\"prompt\":\"Please explain to me how LLMs work\",\"raw_prompting\":true,\"return_likelihoods\":\"NONE\",\"seed\":0,\"stop_sequences\":[\"string\"],\"stream\":true,\"temperature\":0,\"truncate\":\"END\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.cohere.com/v1/generate")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"end_sequences\":[\"string\"],\"frequency_penalty\":0,\"k\":0,\"max_tokens\":0,\"model\":\"string\",\"num_generations\":0,\"p\":0,\"presence_penalty\":0,\"preset\":\"my-preset-a58sbd\",\"prompt\":\"Please explain to me how LLMs work\",\"raw_prompting\":true,\"return_likelihoods\":\"NONE\",\"seed\":0,\"stop_sequences\":[\"string\"],\"stream\":true,\"temperature\":0,\"truncate\":\"END\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cohere.com/v1/generate");
request.Content = new StringContent("{\"end_sequences\":[\"string\"],\"frequency_penalty\":0,\"k\":0,\"max_tokens\":0,\"model\":\"string\",\"num_generations\":0,\"p\":0,\"presence_penalty\":0,\"preset\":\"my-preset-a58sbd\",\"prompt\":\"Please explain to me how LLMs work\",\"raw_prompting\":true,\"return_likelihoods\":\"NONE\",\"seed\":0,\"stop_sequences\":[\"string\"],\"stream\":true,\"temperature\":0,\"truncate\":\"END\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "generations": [
    {
      "id": "string",
      "index": 0,
      "likelihood": 0,
      "text": "string",
      "token_likelihoods": [
        {
          "likelihood": 0,
          "token": "string"
        }
      ]
    }
  ],
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "prompt": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

Search documentation

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations

Parameters

Request body

Responses

Headers

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations