Chat Generate API

Generate AI-powered text responses using the Recoup chat system. This endpoint processes chat requests and returns generated text along with metadata about the generation process.

Endpoint

POST https://chat.recoupable.com/api/chat/generate

Authentication

All requests to this endpoint must be authenticated using an API key header:

Header	Type	Required	Description
x-api-key	string	Yes	Your Recoup API key. See Getting Started for how to create and manage keys.

Parameters

Name	Type	Required	Description
prompt	string	No	Single text prompt for the assistant. Required if `messages` is not provided.
messages	array	No	Array of UIMessage objects for context. Required if `prompt` is not provided.
artistId	string	No	The unique identifier of the artist (optional)
model	string	No	The AI model to use for text generation (optional)
excludeTools	array	No	Array of tool names to exclude from execution (e.g., `["create_scheduled_actions"]`)

Exactly one of messages or prompt should be provided in each request.

Request Examples

cURL

curl -X POST "https://chat.recoupable.com/api/chat/generate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "Hello, how are you?",
    "model": "openai/gpt-5-mini",
    "excludeTools": ["create_scheduled_actions"]
  }'

Example Response

{
  "text": [
    {
      "type": "text",
      "text": "Hello! I'm here to help you with any questions or tasks you might have. How can I assist you today?"
    }
  ],
  "reasoningText": "The user greeted me, so I should respond with a friendly greeting and offer to help.",
  "sources": [],
  "finishReason": "stop",
  "usage": {
    "inputTokens": 8365,
    "outputTokens": 106,
    "totalTokens": 8471,
    "reasoningTokens": 64,
    "cachedInputTokens": 0
  },
  "response": {
    "messages": [],
    "headers": {},
    "body": {}
  }
}

Response Properties

Property	Type	Description
text	Array<ContentPart<TOOLS>>	Array of content parts from the AI model response. Learn more about ContentPart types
reasoningText	string	Optional reasoning or explanation for the response
sources	array	Optional array of sources used for the response
finishReason	string	The reason why the generation finished
usage	object	Token usage information with detailed breakdown
usage.inputTokens	number	Number of input tokens processed
usage.outputTokens	number	Number of output tokens generated
usage.totalTokens	number	Total tokens used (input + output)
usage.reasoningTokens	number	Number of reasoning tokens used
usage.cachedInputTokens	number	Number of cached input tokens
response	object	Additional response metadata and information

Notes

The text field contains an array of content parts that need to be processed to extract the actual text content
Use the finishReason to determine if the generation completed successfully
The usage object provides detailed token consumption information for cost tracking
The reasoningText field contains the AI model's internal reasoning process