Create a chat completion

POST

/v1/chat/completions

const url = 'https://api.aderra.ai/v1/chat/completions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"model":"deepseek-v4.1-flash-uncensored","max_tokens":1024,"messages":[{"role":"user","content":"Write a haiku about the sea."}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aderra.ai/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "deepseek-v4.1-flash-uncensored", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Write a haiku about the sea." } ] }'

OpenAI Chat Completions. Send the whole conversation in messages; nothing is stored between requests. Set stream: true for server-sent events: one data: line per chunk, ending with data: [DONE]. A streamed reply always carries a final chunk with usage (Aderra sets stream_options.include_usage for you).

Only the fields listed below are forwarded to the model. Anything else is dropped, not refused. n must be 1.

A request for an -uncensored model may be served on its standard sibling when the request plainly does not need the unfiltered model (faster and cheaper). The x-aderra-model-used response header always names the model that answered, and you pay that model’s price.

Authorizations

bearerAuth

Request Body^required

application/json

object

model

required

A model id from GET /v1/models.

string

messages

required

Array<object>

object

role

required

string

Allowed values: system developer user assistant tool

content

Text, or an array of content parts (text, image_url). Image parts are read only by models whose input_modalities include image.

One of:

string
Array<object>

string

name

string

tool_calls

Array<object>

object

key

additional properties

any

tool_call_id

string

key

additional properties

any

max_tokens

Output ceiling, capped at the model’s output limit. Absent (or not a positive integer) means the limit itself. The hold is sized on it.

integer

>= 1

max_completion_tokens

Same as max_tokens; used when max_tokens is absent.

integer

>= 1

stream

boolean

stream_options

object

include_usage

boolean

temperature

number

top_p

number

top_k

integer

stop

One of:

string
Array<string>

string

tools

Array<object>

object

key

additional properties

any

tool_choice

One of:

string
object

string

parallel_tool_calls

boolean

response_format

object

key

additional properties

any

reasoning_effort

Thinking budget. Some models think by default: when you set a max_tokens below 16,384 and send no reasoning_effort, reasoning or thinking, Aderra may send minimal for you so the budget goes to the answer.

string

reasoning

object

key

additional properties

any

thinking

object

key

additional properties

any

seed

integer

presence_penalty

number

frequency_penalty

number

logit_bias

object

key

additional properties

number

logprobs

boolean

top_logprobs

integer

modalities

Array<string>

Must be 1 or absent.

integer

Allowed values: 1

Example

{
  "model": "deepseek-v4.1-flash-uncensored",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about the sea."
    }
  ]
}

Responses

200

The completion. JSON, or text/event-stream when stream is true.

object

string

object

string

Allowed value: chat.completion

created

integer

model

string

choices

Array<object>

object

index

integer

message

object

role

string

content

string | null

tool_calls

Array<object>

object

key

additional properties

any

finish_reason

string

usage

object

prompt_tokens

integer

completion_tokens

Includes any thinking tokens.

integer

total_tokens

integer

prompt_tokens_details

object

cached_tokens

integer

Example

{
  "object": "chat.completion"
}

data: {chat.completion.chunk} lines, then data: [DONE].

string

Example

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Waves"}}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":812,"completion_tokens":17,"total_tokens":829}}

data: [DONE]

Headers

x-aderra-model-used

string

Example

deepseek-v4.1-flash

The model that actually answered, and the one you are billed for.

x-aderra-route

string

Example

kept:not_unfiltered

Why that model answered: kept:<reason>, downgraded-from:<model> or forced-unfiltered.

x-aderra-reservation

string format: uuid

The id of the credit hold for this call. Quote it when you contact support about a charge.

400

invalid_json, unknown_model (with the list of known ids), unsupported_n.

application/json

One of:

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object

error

required

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

401

The key is missing, unknown or revoked: {"error": "unauthorized"}.

application/json

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object

error

required

string

message

string

Example

{
  "error": "unauthorized"
}

402

api_wallet_empty: the API wallet cannot pay for this request (lower max_tokens or add funds). key_spend_cap_reached: the key hit its monthly cap. Terminal keys get their plan’s refusals instead (insufficient_credits, plan_required).

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error",
    "code": "api_wallet_empty",
    "message": "Your API wallet does not have enough credits for this request. Top up at https://aderra.ai/developers — API keys draw on the API wallet, not your plan."
  }
}

403

account_suspended: the account behind the key is suspended.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

413

request_too_large: the body is over the size limit.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

429

rate_limited: the key passed its requests per minute. too_many_concurrent_requests: the account already has 8 requests in progress. Wait for Retry-After seconds.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "This API key is limited to 60 requests a minute. Try again in 12 seconds, or raise the key's limit at https://aderra.ai/developers."
  }
}

Headers

Retry-After

integer

Example

Whole seconds to wait before trying again.

502

The model failed or could not be reached. Not charged. {"error":"upstream_unreachable"} or an upstream_error object whose code is the upstream HTTP status (a number).

application/json

One of:

object
object

object

error

object

type

string

Allowed value: upstream_error

code

integer

message

string

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object

error

required

string

message

string

Example

{
  "error": {
    "type": "upstream_error",
    "code": 429,
    "message": "The model is busy right now. Try again in a few seconds."
  }
}

503

overloaded_error: Aderra is busy receiving other large requests. Retry after Retry-After (5) seconds.

application/json

object

type

required

string

Allowed value: error

error

required

object

type

string

Allowed values: invalid_request_error authentication_error permission_error billing_error rate_limit_error request_too_large api_error overloaded_error

message

string

Example

{
  "type": "error",
  "error": {
    "type": "invalid_request_error"
  }
}

Headers

Retry-After

integer

Example

Whole seconds to wait before trying again.

Create a chat completion

Authorizations

Request Bodyrequired

Example

Responses

200

Example

Example

Headers

Example

Example

400

Example

401

Example

402

Example

403

Example

413

Example

429

Example

Headers

Example

502

Example

503

Example

Headers

Example

Request Body^required