Skip to content

API reference

The Inco API is compatible with the OpenAI and Anthropic SDKs: point an existing client at our base URL and change nothing else. Create a key on the API keys page.

On this page

Base URL

All endpoints are served from a single host. For the OpenAI SDK, set base_url to the /v1 path; the Anthropic SDK uses the host root.

OpenAI SDKbase_url
https://api.inco.ai/v1

Authentication

Send your sk-inco-… key as a bearer token in the Authorization header. Keys are stored hashed and shown only once, when you create them.

Authorization header
Authorization: Bearer sk-inco-...

An owner or admin can limit a workspace's keys to listed IPv4 addresses and networks with the IP allowlist under Settings. A request from any other address gets a 403 with the code ip_address_not_allowed, and its message names the address it came from.

Models and pricing

The catalog is machine-readable. GET /v1/models lists every model with its context length and prices. Without a key it returns the public catalog; with your key, it lists the models your workspace may call, at its prices. Prices are US dollars per 1M tokens: input, cached_input (input tokens served from the cache) and output. An entry also carries license, license_url, model_card_url and parameters when the catalog records them, and modalities once we have verified what the model reads: image in its input means images reach it on every endpoint, and video that a video does as a video_url part on /v1/chat/completions, the one endpoint that carries video. GET /v1/models/{id} returns one entry.

cURL/v1/models
curl https://api.inco.ai/v1/models
One entryglm-5.3-flash
{
  "id": "glm-5.3-flash",
  "object": "model",
  "created": 1790576061,
  "owned_by": "inco",
  "name": "GLM 5.3 Flash",
  "mode": "standard",
  "context_length": 1048576,
  "pricing": {
    "input": 0.15,
    "cached_input": 0.03,
    "output": 0.5
  },
  "reasoning": {
    "modes": {
      "supported": [
        "enabled"
      ],
      "default": "enabled"
    },
    "efforts": {
      "supported": [
        "low",
        "high",
        "max"
      ],
      "default": "max"
    }
  },
  "modalities": {
    "input": [
      "text",
      "image",
      "video"
    ],
    "output": [
      "text"
    ]
  },
  "license": "MIT",
  "license_url": "https://huggingface.co/zai-org/GLM-5.3-Flash/blob/main/LICENSE",
  "model_card_url": "https://huggingface.co/zai-org/GLM-5.3-Flash",
  "parameters": 320000000000
}

Quickstart

The same key and models work with all three APIs: OpenAI Chat Completions (POST /v1/chat/completions), OpenAI Responses (POST /v1/responses) and Anthropic Messages (POST /v1/messages). Pick the tab for your SDK.

cURL/v1/chat/completions
curl https://api.inco.ai/v1/chat/completions \
  -H "Authorization: Bearer $INCO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm-5.3-flash",
  "messages": [
    {
      "role": "user",
      "content": "Explain RoPE in one sentence."
    }
  ]
}'
Pythonopenai
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.inco.ai/v1",
    api_key=os.environ["INCO_API_KEY"],
)

chat = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role":"user","content":"Explain RoPE in one sentence."}],
)
print(chat.choices[0].message.content)
Nodeopenai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.inco.ai/v1",
  apiKey: process.env.INCO_API_KEY,
});

const chat = await client.chat.completions.create({
  "model": "glm-5.3-flash",
  "messages": [
    {
      "role": "user",
      "content": "Explain RoPE in one sentence."
    }
  ]
});
console.log(chat.choices[0].message.content);

Streaming

Every endpoint streams with server-sent events when you pass stream: true. Usage is metered on the full response either way; a Chat Completions stream sends its usage chunk only when you set stream_options.include_usage. A stream that fails part-way ends with the API's error event instead of its usual end. A stream runs for up to an hour: one still going then ends with a 504 request_timeout error event and is billed for the output it sent.

cURLstream: true
curl https://api.inco.ai/v1/chat/completions \
  -H "Authorization: Bearer $INCO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm-5.3-flash",
  "messages": [
    {
      "role": "user",
      "content": "Explain RoPE in one sentence."
    }
  ],
  "stream": true
}'

Reasoning

A model's reasoning comes back in each API's own shape: reasoning_content on Chat Completions, thinking blocks on Messages, reasoning items on Responses. Whether it reasons when a request says nothing is the model's own default. Set the effort the way your SDK does: reasoning_effort on Chat Completions, reasoning.effort on Responses, output_config.effort on Messages, where thinking turns reasoning on or off (budget_tokens asks for reasoning at the model's default effort). none, or thinking: {"type": "disabled"}, stops it on a model that lists it.

GET /v1/models lists each model's reasoning: for its thinking modes (enabled, adaptive where the model decides whether to think, disabled) and its efforts, the supported values and the default a request naming none gets. A model without the disabled mode always reasons. A value outside its lists is the model's to handle: it may take the nearest level or refuse it with a 400.

Conversation state

Requests are stateless: nothing is kept between them. Send the whole conversation each turn, in messages, or in input on Responses with each response's output items included, as clients that set store: false do. previous_response_id and conversation are refused with a 400.

Errors

400The body is not JSON, doesn't fit the API, or stopped arriving before it was whole, the prompt is longer than the model's context, sets a parameter the model cannot honour that would change the answer, or carries more than 100,000 Responses input items. A model honours the parameters it documents; a best-effort hint it lacks (seed, parallel_tool_calls) or a label (user, metadata) is ignored, and any other is refused rather than ignored in silence. param names the field when there is one; a model's own refusal has no code.invalid_jsoninvalid_request_bodyrequest_body_incompletecontext_length_exceededunsupported_parametertoo_many_input_items
401No API key was sent, or it is invalid, revoked or expired.missing_api_keyinvalid_api_keyapi_key_expired
402Your credit balance is empty. Add credit to resume.credit_balance_exhausted
403The workspace's IP allowlist doesn't include the request's address, or the workspace hasn't agreed to the updated Terms of Service, has turned relayed models off, can't use relayed models in its country, or is suspended or archived.ip_address_not_allowedterms_not_acceptedrelayed_models_not_allowedrelayed_models_unavailable_in_countryworkspace_suspendedworkspace_archived
404No such endpoint, or no such model for your key: a private model your workspace can't use reads as one that doesn't exist.model_not_foundendpoint_not_found
413The request body is larger than the API accepts.request_too_large
429You reached a per-minute rate limit (retry after the seconds in Retry-After) or your workspace's monthly spend limit (no Retry-After; raise it on the Limits page, or wait until it resets on the 1st (UTC)).rate_limit_exceededworkspace_spend_limit_exceeded
503The model or the API is briefly out of capacity. Retry with backoff.server_is_overloadedservice_unavailable
504The model didn't finish in time. Retry, or stream long generations. A stream cut at its one-hour limit is billed for the output it sent; ask for less output rather than retrying it.request_timeout
5xxAny other failure on our side. Retry with backoff.

Errors use each API's own format. OpenAI-style endpoints return { error: { message, type, param, code } }, and /v1/messages returns Anthropic's { type: "error", error: { type, message }, request_id }. The message is one plain sentence that names the field at fault (messages[0].role: …), and code names the cause.

Every response carries an x-request-id header, and /v1/messages also sends request-id, which Anthropic's SDKs read. It is the ID the request is listed under on the Logs page, served or refused, and a chat completion, message or response carries it in its id field. Include it when you contact support.

Billing

Access is prepaid: each request is metered to the token and paid from your credit balance at the model's rates, with cached input tokens at the lower cached-input rate. When the balance reaches zero, requests return 402 until you add credit. Track spend on the Usage page, and every request, served or refused, on the Logs page.

An owner or admin can also set a monthly spend limit on the Limits page. It is checked before every request, counting requests still running, so spend cannot exceed it. Once it is reached, requests get a 429 that says so until the first of the next month (UTC), or until you raise the limit. Spend alerts at a share of the limit appear on the Overview.

Rate limits

Rate limits apply to your workspace, per model and per minute: requests, input tokens and output tokens. Cached input does not count toward the input-token limit. All of a workspace's keys share a model's limits, and each model has its own. Capacity comes back continuously rather than all at once each minute, a sixtieth of the limit each second, so a faster burst is refused with a Retry-After header. Your current limits are on the Limits page; to raise them, use Request an increase there or email [email protected].

Input tokens are estimated from the prompt when a request arrives and corrected to the actual uncached count when it ends, so a request larger than the remaining input budget is refused up front. max_tokens never counts. Output tokens are counted as they are generated: a long response uses the limit while it streams, and a rate limit never cuts a response short.

Every response reports the limits for the model it called, in headers your SDK already reads:

  • OpenAI-style endpoints: x-ratelimit-limit-requests, x-ratelimit-remaining-requests and x-ratelimit-reset-requests (a duration such as 60s), and the same three for tokens (input) and output-tokens.
  • /v1/messages: anthropic-ratelimit-requests-limit, -remaining and -reset (an RFC 3339 time), the same for input-tokens and output-tokens, and tokens for whichever of the two is tighter.

Remaining is what you can use now; reset is when the limit is fully replenished.

A 429 always means you reached one of your own limits, and its code says which. A rate limit, rate_limit_exceeded, carries Retry-After: the seconds until the request would be admitted, while the headers above carry the numbers. Retrying sooner will not help: wait, slow down, or send smaller requests. The monthly spend limit, workspace_spend_limit_exceeded, has no Retry-After: requests stay refused until you raise the limit or the month resets (UTC). A model that is briefly out of capacity answers 503 instead (overloaded_error on /v1/messages); retry it with backoff, as the OpenAI and Anthropic SDKs do on their own.

FAQ