Completions API

The Completions API provides access to AI language model completions. This endpoint allows you to send messages and receive AI-generated responses.

Base URL

https://dreamsolve.ai/api/v1

Authentication

This endpoint requires authentication via Bearer token in the Authorization header.

Authorization: Bearer YOUR_ACCESS_TOKEN

---

Create Completion

Generate a completion from the AI model.

POST /api/v1/completions

Request Body

{
  "messages": [
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "stream": false,
  "max_tokens": 1000,
  "tools": [],
  "tool_choice": "auto"
}

Field	Type	Required	Description
messages	array	Yes	Array of message objects
stream	boolean	No	Enable streaming response (default: false)
max_tokens	number	No	Maximum tokens to generate (default: 1000, max: 100000)
tools	array	No	Tool definitions for function calling
tool_choice	string	No	Tool selection mode

Message Object

{
  "role": "user",
  "content": "Your message here"
}

Field	Type	Description
role	string	Message role: user, assistant, or system
content	string	The message content

---

Non-Streaming Response

When stream: false (default), the response is returned as a complete JSON object.

Response

{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "model": "claude-3-sonnet",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 12
  }
}

---

Streaming Response

When stream: true, the response is returned as a stream of server-sent events.

Headers

Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

Stream Format

The stream contains chunks of the response as they are generated.

---

Tool Calling

You can provide tools for the model to use during completion.

Tool Definition

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": ["location"]
      }
    }
  ],
  "tool_choice": "auto"
}

Tool Choice Options

Value	Description
auto	Model decides whether to use tools
any	Model must use at least one tool
none	Model cannot use tools

---

Error Responses

Status Code	Description
400	Bad Request - Invalid or missing messages
401	Unauthorized - Invalid or missing authentication
500	Internal Server Error

Example Error Responses

{
  "error": "Unauthorized. Please log in."
}

{
  "error": "Messages are required and must be an array"
}

{
  "error": "Failed to get AI response"
}

---

Example Usage

Simple completion

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Explain quantum computing in simple terms" }
    ],
    "max_tokens": 500
  }' \
  https://dreamsolve.ai/api/v1/completions

Completion with system prompt

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a helpful coding assistant." },
      { "role": "user", "content": "Write a Python function to reverse a string" }
    ],
    "max_tokens": 1000
  }' \
  https://dreamsolve.ai/api/v1/completions

Streaming completion

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Write a short story about a robot" }
    ],
    "stream": true,
    "max_tokens": 2000
  }' \
  https://dreamsolve.ai/api/v1/completions

---

Rate Limiting

Completion requests may be subject to rate limiting based on token usage. If you exceed limits, you will receive a 429 status code.

Usage Tracking

Token usage is automatically tracked for billing and analytics purposes. You can view your usage in the DreamSolve dashboard.