Skip to content
LLM Router
Edgee SDKs

TypeScript SDK - Send Method

Complete guide to the send() method in the TypeScript SDK.

The send() method is used to make non-streaming chat completion requests to the Edgee AI Gateway. It returns a Promise<SendResponse> with the model's response.

Arguments

The send() method accepts a single SendOptions object with the following properties:

PropertyTypeDescription
model stringThe model identifier to use (e.g., "openai/gpt-5.2")
inputstring | InputObjectThe input for the completion. Can be a simple string or a structured InputObject

Input Types

String Input

When input is a string, it's automatically converted to a user message:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'What is the capital of France?'
});

// Equivalent to: input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] }
console.log(response.text);
// "The capital of France is Paris."

InputObject

When input is an InputObject, you have full control over the conversation:

PropertyTypeDescription
messages Message[]Array of conversation messages
toolsTool[]Array of function tools available to the model
tool_choiceToolChoiceControls which tool (if any) the model should call. See Tools documentation for details
tagsstring[]Optional tags to categorize and label the request for analytics and filtering. Can also be sent via the x-edgee-tags header (comma-separated)
tool_result_trimmingbooleanTurn tool-result trimming on or off for this request. Omit it to keep the API key setting.
tool_surface_reductionbooleanTurn MCP tool surface reduction on or off for this request. The threshold still comes from the API key. Omit it to keep the API key setting.
output_brevitybooleanTurn output brevity on or off for this request. Omit it to keep the API key setting.

Example with InputObject:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'What is 2+2?' }
    ]
  }
});

console.log(response.text);
// "2+2 equals 4."

Example with Tags:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'Summarize this article' }
    ],
    tags: ['summarization', 'production', 'user-123']
  }
});

Message Object

Each message in the messages array has the following structure:

PropertyTypeDescription
role stringThe role of the message sender: "system", "developer", "user", "assistant", or "tool"
contentstringThe message content. Required for system, user, tool and developer roles. Optional for assistant when tool_calls is present
namestringOptional name for the message sender
tool_callsToolCall[]Array of tool calls made by the assistant. Only present in assistant messages
tool_call_idstringID of the tool call this message is responding to. Required for tool role messages

Message Roles

  • system: System instructions that set the behavior of the assistant
  • developer: Instructions provided by the application developer, prioritized ahead of user messages.
  • user: Instructions provided by an end user.
  • assistant: Assistant responses (can include tool_calls)
  • tool: Results from tool/function calls (requires tool_call_id)

Example - System and User Messages:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What is 2+2?' },
      { role: 'assistant', content: '2+2 equals 4.' },
      { role: 'user', content: 'What about 3+3?' }
    ]
  }
});

console.log(response.text);
// "3+3 equals 6."

For complete tool calling examples and best practices, see Tools documentation.

Return Value

The send() method returns a Promise<SendResponse> with the following structure:

SendResponse Object

PropertyTypeDescription
choicesChoice[]Array of completion choices (typically one)
usageUsage | undefinedToken usage information (if provided by the API)
compressionCompression | undefinedToken compression metrics (if compression was applied)

Choice Object

Each choice in the choices array contains:

PropertyTypeDescription
indexnumberThe index of this choice in the array
messageMessageThe assistant's message response
finish_reasonstring | nullReason why the generation stopped. Possible values: "stop", "length", "tool_calls", "content_filter", or null

Example - Handling Multiple Choices:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Give me a creative idea.'
});

// Process all choices
response.choices.forEach((choice, index) => {
  console.log(`Choice ${index}:`, choice.message.content);
  console.log(`Finish reason: ${choice.finish_reason}`);
});

Message Object (in Response)

The message in each choice has:

PropertyTypeDescription
rolestringThe role of the message (typically "assistant")
contentstring | nullThe text content of the response. null when tool_calls is present
tool_callsToolCall[] | undefinedArray of tool calls requested by the model (if any). See Tools documentation for details

Usage Object

Token usage information (when available):

PropertyTypeDescription
prompt_tokensnumberNumber of tokens in the prompt (after compression if applied)
completion_tokensnumberNumber of tokens in the completion
total_tokensnumberTotal tokens used (prompt + completion)

Example - Accessing Token Usage:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Explain quantum computing briefly.'
});

if (response.usage) {
  console.log(`Prompt tokens: ${response.usage.prompt_tokens}`);
  console.log(`Completion tokens: ${response.usage.completion_tokens}`);
  console.log(`Total tokens: ${response.usage.total_tokens}`);
}

Compression Object

Token compression metrics (when compression is applied):

PropertyTypeDescription
saved_tokensnumberNumber of tokens saved by compression
cost_savingsnumberEstimated cost savings in micro-units (e.g. 27000 = $0.027)
reductionnumberPercentage reduction (e.g. 18 = 18%, may be fractional)
time_msnumberTime taken for compression in milliseconds

Example - Accessing Compression Metrics:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages, // a conversation that includes tool calls and their results
    tool_result_trimming: true,
  }
});

if (response.compression) {
  console.log(`Saved tokens: ${response.compression.saved_tokens}`);
  console.log(`Reduction: ${response.compression.reduction}%`);
  console.log(`Cost savings: $${(response.compression.cost_savings / 1_000_000).toFixed(3)}`);
  console.log(`Time: ${response.compression.time_ms} ms`);
}

Convenience Properties

The SendResponse class provides convenience getters for easier access:

PropertyTypeDescription
textstring | nullShortcut to choices[0].message.content
messageMessage | nullShortcut to choices[0].message
finishReasonstring | nullShortcut to choices[0].finish_reason
toolCallsToolCall[] | nullShortcut to choices[0].message.tool_calls

Example - Using Convenience Properties:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Hello!'
});

// Instead of: response.choices[0].message.content
console.log(response.text);

// Instead of: response.choices[0].message
console.log(response.message);

// Instead of: response.choices[0].finish_reason
console.log(response.finishReason);

// Instead of: response.choices[0].message.tool_calls
if (response.toolCalls) {
  console.log('Tool calls:', response.toolCalls);
}

Error Handling

The send() method can throw errors in several scenarios:

try {
  const response = await edgee.send({
    model: 'gpt-5.2',
    input: 'Hello!'
  });
} catch (error) {
  if (error instanceof Error) {
    // API errors: "API error {status}: {message}"
    // Network errors: Standard fetch errors
    console.error('Request failed:', error.message);
  }
}

Common Errors

  • API errors: Error: API error {status}: {message} - The API returned an error status
  • Network errors: Standard fetch network errors
  • Invalid input: Errors from invalid request structure