API reference overview

OpenToken is an OpenAI-compatible LLM API gateway. It exposes a small, RESTful HTTP API that mirrors the OpenAI shape, so existing OpenAI SDKs and tooling work by changing only the base URL and key.

All requests go to a single base URL:

https://api.opentoken.kr/v1

Requests and responses are JSON. Model ids use the {provider}/{model} format — see Models for the registered ids.

Authentication

Every request must include your secret API key as a Bearer token. Keys start with sk-optk-.

Authorization: Bearer sk-optk-...

Keep keys server-side and pass them through the OPENTOKEN_API_KEY environment variable. Customer-issued keys start with sk-optk-. A missing or invalid key returns a 401 with type authentication_error; the code varies — missing_auth (no Bearer token), invalid_key, or expired_key. See Authentication for the full identity model.

Endpoints

The API exposes three Bearer-authed /v1 endpoints, plus a public healthcheck:

• POST /v1/chat/completions — create a chat completion. Returns a chat.completion object, or a stream of Server-Sent Events when stream is true. See Create chat completion.
• POST /v1/embeddings — create embeddings. Returns an OpenAI-compatible embeddings object. Currently supports google/text-embedding-004 (input-only). A model without embeddings support returns 400 embeddings_unsupported.
• GET /v1/models — list the models available to your key. See List models.
• GET /health — public, unauthenticated healthcheck. Returns {"status":"ok"}.

Errors

Errors use the OpenAI-compatible envelope. Every failure returns a JSON body with an error object:

{
  "error": {
    "message": "model \"openai/gpt-4o\" not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Over a streaming response an error can arrive after a 200 as one more data: frame whose payload is the error envelope (not an SSE event: error), followed by data: [DONE]. See Errors for the full list of status codes and code values.

Next steps