How to use LM Studio OpenAI compatible interface: Local API access tutorial

LM Studio can turn locally loaded models into OpenAI compatible interfaces. For existing projects, there is usually no need to rewrite the calling logic: change base_url of the OpenAI client to the local address of LM Studio, and then change model to the model identifier in LM Studio.

The most commonly used addresses are:

1

http://localhost:1234/v1

It is suitable for plugging into existing Python, JavaScript, C# or other OpenAI client code. The following instructions are in the order of “run through first, then access the project”.

Let’s talk about the conclusion first

To use LM Studio’s OpenAI-compatible interface, you only need to complete four steps:

1. Start the local server in LM Studio’s Developer page.
2. Load a chat model.
3. Request http://localhost:1234/v1/models, confirm model ID.
4. Change client base_url to http://localhost:1234/v1.

Minimal Python writing:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

response = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 KV cache。"}
    ],
)

print(response.choices[0].message.content)

api_key="lm-studio" is just a placeholder value for OpenAI SDK when authentication is not enabled; if you enable API token in the LM Studio service settings, it should be changed to the real token.

Step 1: Start the LM Studio local server

Open LM Studio, enter the Developer page, and turn on the Start server switch. The default service will listen for:

1

http://localhost:1234

You can also use the LM Studio command line tool to start:

1

lms server start

If lms is not available on your computer, you can install the CLI according to the official LM Studio documentation:

1

npx lmstudio install-cli

Service startup only means that the API port is listening, but does not mean that there is a model that can be reasoned about. Continue to load a model in the Chat or Developer page, or load it with lms load.

Step 2: Get the model ID first

Don’t guess the model parameter based on the file name. The most stable way is to request a list of models:

1

curl http://localhost:1234/v1/models

Windows PowerShell can be used:

1

Invoke-RestMethod http://localhost:1234/v1/models

The returned data list will have the model identifier. Then fill in model with the actual returned ID in the request.

This step can avoid two common problems: the model has been downloaded but not loaded, or the name written in the code is inconsistent with the model ID currently exposed by LM Studio.

Step 3: Test Chat Completions with curl

First test with the most intuitive OpenAI compatible endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的 LM Studio 模型 ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "解释什么是向量数据库。"}
    ],
    "temperature": 0.7
  }'

When successful, the answer is usually:

1

choices[0].message.content

Chat Completions automatically apply the chat model’s prompt template. As long as the model itself is of chat/instruct type, there is usually no need to manually splice special control tokens on the client side.

How to replace OpenAI with Python project

If the project originally uses the OpenAI Python SDK, there are usually only two focuses: base_url and model.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

completion = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "system", "content": "你是一名 Python 助手。"},
        {"role": "user", "content": "写一个读取 JSON 文件的最小示例。"},
    ],
    temperature=0.2,
    max_tokens=500,
)

print(completion.choices[0].message.content)

The advantage of this is that the application layer still uses the objects and return formats of the OpenAI SDK, and the backend can switch between the cloud OpenAI API and the local LM Studio.

But “compatibility” does not mean that every cloud model feature can be copied as is. Availability of tool calls, structured output, visual input, inference content, and the Responses API is still dependent on the LM Studio version, current model capabilities, and corresponding endpoint support.

Streaming output

Set stream=True in Chat Completions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

stream = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[{"role": "user", "content": "写一首四行小诗。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Streaming output is suitable for chat interfaces, terminal tools, and long answers. It improves the user waiting experience and does not make the local model itself generated faster.

How to choose between Embeddings, Responses and native REST API

LM Studio’s OpenAI compatibility layer includes common endpoints:

LM Studio also has its own native interface. The current recommended path is /api/v1/*, such as /api/v1/chat and /api/v1/models. The native API is more suitable for projects that require model loading/unloading, stateful chat, MCP or LM Studio-specific capabilities.

Simple judgment: If you already have an OpenAI SDK project, use /v1 first; if a new project requires in-depth management of local models or uses LM Studio’s exclusive capabilities, then consider /api/v1.

Structured output and tool calls

LM Studio’s OpenAI compatibility layer supports tool calls and structured output in the corresponding endpoints, but first confirm two things:

1. The model you load must have reliable tool calling or JSON output capabilities.
2. The versions of LM Studio and client SDK must be new enough.

Don’t assume that the model can stably generate results that conform to the schema just because there are no errors in the request. Testing should be done using real parameters, abnormal branches and multiple rounds of requests before going online.

Troubleshooting common errors

1. Connection refused or Connection refused

First confirm that the server in the Developer page has been started, and then test:

1

curl http://localhost:1234/v1/models

If you can’t connect here, first check the port, whether LM Studio is still running, or whether the local security software blocks the local port.

2. 404 Not Found

The most common reason is that the path is written incorrectly. OpenAI compatible chat endpoints are:

1

/v1/chat/completions

Not /api/v1/chat/completions. The latter belongs to another set of native API paths.

3. The model does not exist or an empty list is returned

First load the model in LM Studio and then check the return of /v1/models. model in the code must use the actual returned identifier, and do not copy other people’s model names.

4. Can answer but the format is strange

Check that the base model is loaded instead of the instruct/chat model; also check that the chat template is automatically applied by LM Studio. For tool calls and JSON output, also confirm that the model actually supports the capability.

5. The LAN device cannot be accessed

LM Studio can configure services to the local network on the Developer page. After enabling network access, you also need to confirm the firewall, listening address and API token settings. Do not expose unauthenticated local model services directly to the public network.

A minimal access checklist

1
2
3
4
5
6
7

1. LM Studio Developer -> Start server
2. 加载一个 instruct/chat 模型
3. curl http://localhost:1234/v1/models
4. 客户端 base_url 改为 http://localhost:1234/v1
5. model 填实际返回的 ID
6. 用 chat/completions 跑通单轮请求
7. 再测试流式、工具调用、Embeddings 或结构化输出

Run through the minimum request first, and then connect RAG, Agent or editor plug-in, troubleshooting will be much easier.

Summarize

LM Studio’s OpenAI compatible interface is suitable for connecting local models to existing OpenAI SDK projects. The most critical thing is not to copy a piece of code, but to confirm that the service is started, the model is loaded, base_url points to /v1, and model uses the actual model ID.

If what you need is deeper local model management, stateful chat, or MCP, LM Studio’s /api/v1/* native interface will be more suitable; if the goal is quick compatibility with old projects, continuing to use /v1/chat/completions is usually the easiest thing to do.

refer to:

• LM Studio OpenAI Compatibility Endpoints
• LM Studio Chat Completions
• LM Studio Local API Server
• LM Studio REST API