iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Ollama provides a REST API for running language and embedding models locally or through Ollama Cloud. Local applications call http://localhost:11434/api without authentication; hosted applications call https://ollama.com/api with an Authorization: Bearer API key. Use POST /api/generate for a single prompt, POST /api/chat for role-based conversations and tool calls, and POST /api/embed for vectors. Responses stream as newline-delimited JSON unless you set "stream": false.
This guide shows the request shapes, streaming loop, model-management calls, embeddings, tool calling, OpenAI-compatible integration, authentication rules, and production checks you need to build reliably. Ollama’s own introduction summarizes the purpose as: “Use Ollama’s API to build applications with cloud or local models.”
What is the Ollama API and which endpoint should I use?
The native API is a JSON-over-HTTP interface. You choose the endpoint from the kind of work your application performs, then send a model name plus the relevant prompt, messages, or embedding input.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →| Endpoint | Best use | Important request fields | Default response behavior |
|---|---|---|---|
POST /api/generate |
One prompt or completion | model, prompt; also suffix, images, format, options, system, template, raw, keep_alive |
Streams JSON objects |
POST /api/chat |
Multi-turn, role-based conversations and tools | model, ordered messages, optional tools, stream |
Streams JSON objects |
POST /api/embed |
Vector embeddings for one or many inputs | model, input, truncate, options, keep_alive, optional dimensions |
Returns an embeddings array |
GET /api/tags |
List models installed on a local server | None | One JSON response |
GET /api/ps |
See models currently loaded | None | One JSON response |
GET /api/version |
Read the running API version | None | One JSON response |
Native cloud requests use the same path after the cloud base URL. Local model-management operations such as creating or deleting models require a local server.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
How do I call the Ollama API locally or in the cloud?
Use the local base URL when the Ollama server and model are on the same machine. Use the cloud base URL when you want Ollama-hosted inference; cloud calls require a bearer key.
Local request prerequisites
- Run an Ollama server on the machine that will receive the request.
- Install or pull the model named in the request. A missing model produces an error rather than downloading silently in every endpoint.
- Send requests to
http://localhost:11434/apiand omit the authorization header.
Hosted request with a bearer key
Keep the key in an environment variable and send it only to the hosted endpoint:
export OLLAMA_API_KEY='your-key'
curl https://ollama.com/api/chat
-H 'Authorization: Bearer $OLLAMA_API_KEY'
-H 'Content-Type: application/json'
-d '{
"model": "gemma4:31b",
"messages": [{"role": "user", "content": "Why is the sky blue?"}],
"stream": false
}'For local inference, replace the URL with http://localhost:11434/api/chat, verify that the named model is installed, and remove the Authorization header. Ollama also documents a local-server route for using cloud models after you sign in; that route still uses your local server address while the model is provided through the cloud service.
How do I generate text with /api/generate?
Send a single prompt to POST /api/generate. The generated text is in the response property when you request a non-streaming result.
curl http://localhost:11434/api/generate
-H 'Content-Type: application/json'
-d '{
"model": "llama3.2",
"prompt": "Summarize this paragraph in two sentences.",
"stream": false,
"options": {"temperature": 0.2}
}'A completed response includes done: true. It can also contain total_duration, load_duration, prompt_eval_count, and eval_count; the duration values are reported in nanoseconds. Treat those fields as request telemetry, not as published performance benchmarks.
Options that change generation
systemsupplies a system instruction.templateandrawlet advanced callers control prompt formatting.suffixrequests text after the generated completion.imagesaccepts base64-encoded images for models that support multimodal input.formatacceptsjsonor a JSON schema when you need structured output.keep_alivecontrols how long the model remains loaded after the request.
The older context field is deprecated. For new conversational applications, keep history as messages and use /api/chat.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
How do I send a conversation with /api/chat?
Use POST /api/chat with an ordered messages array. Each message has a role such as system, user, assistant, or tool, plus its content.
curl http://localhost:11434/api/chat
-H 'Content-Type: application/json'
-d '{
"model": "llama3.2",
"messages": [
{"role": "system", "content": "Answer concisely."},
{"role": "user", "content": "Explain HTTP status 429."}
],
"stream": false
}'With stream: false, read the answer from message.content in the completed response. For a continuing conversation, append that assistant message and the next user message to your local messages array before making the next call. Ollama does not require you to maintain a server-side conversation identifier for this pattern.
How does Ollama streaming work?
Native generation and chat calls stream by default. The server sends newline-delimited JSON (NDJSON): each line is a complete JSON object, intermediate objects contain partial text, and the final object has done: true.
When to disable streaming
Set "stream": false when your client expects one JSON document, when a job queue cannot process incremental events, or when you want the simplest error-handling path. This does not change the model or prompt; it changes how the response is delivered.
How to consume a stream safely
- Read the response body line by line rather than trying to parse the entire body as one JSON value.
- Ignore blank lines and parse each non-empty line independently.
- Append each partial
responsevalue for/api/generate, or each partialmessage.contentvalue for/api/chat. - Stop only after receiving the object with
done: true; do not treat an intermediate socket read as completion. - Capture timing and token-count fields from the final object, because those fields are associated with completion.
Pull and push operations can also stream progress. Where the endpoint supports it, set stream: false to receive one status object instead.
Recommended Free Tools
How do I create embeddings with /api/embed?
Send one string or a list of strings as input. The response contains an embeddings array in the same order as the inputs, which makes batching straightforward.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
curl http://localhost:11434/api/embed
-H 'Content-Type: application/json'
-d '{
"model": "embeddinggemma",
"input": ["Why is the sky blue?", "Why is grass green?"],
"truncate": true
}'Important embedding controls
truncatecontrols over-context inputs and defaults totruein the documented API.optionspasses model parameters.keep_alivecontrols retention after the request and has a documented default of five minutes.dimensionscan request a dimension count when the selected model supports it.
The current specification also permits multimodal input objects containing text, image, or audio for models that support multimodal embeddings. Video input is not accepted. Record the embedding model and requested dimensions with every stored vector so a later model change does not silently mix incompatible vectors.
How does Ollama tool calling work?
Tool calling is part of /api/chat. Provide a JSON-Schema function definition in tools when the selected model supports tools; the model may then return tool_calls instead of (or before) a normal answer.
{
"model": "your-tool-capable-model:tag",
"messages": [
{"role": "user", "content": "What is the weather in Paris?"}
],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
}]
}- Validate that the model you selected supports tool calls.
- Inspect the assistant response for
tool_callsand validate every argument against your own schema and authorization rules. - Execute the function in your application, not inside the model.
- Append a message with role
toolcontaining the function result. - Call
/api/chatagain with the expanded message list so the model can formulate its final answer.
Never execute an unvalidated tool argument. Also handle the case where a model that lacks tool support answers normally or emits malformed arguments.
How are Ollama models named and managed?
Model identifiers use the form model:tag, optionally with a namespace such as example/model. If you omit the tag, Ollama uses latest. Pin an explicit tag for reproducible deployments and log that exact identifier with each request.
| Operation | Method and path | Purpose |
|---|---|---|
| Pull | POST /api/pull |
Download a model from the Ollama library |
| Push | POST /api/push |
Upload a model |
| List | GET /api/tags |
List models installed locally |
| Show | POST /api/show |
Inspect model information |
| Create | POST /api/create |
Create a model on a local server |
| Copy | POST /api/copy |
Copy a model name |
| Delete | DELETE /api/delete |
Delete a model from a local server |
| Loaded models | GET /api/ps |
See models currently loaded |
| Version | GET /api/version |
Read the server version |
Pull and push may stream progress. Model loading can add delay to the first request, while keep_alive determines how long a model stays resident after generation or embedding calls.
Can I use the OpenAI SDK with Ollama?
Yes. Ollama exposes an OpenAI-compatible surface at http://localhost:11434/v1 for local use and https://ollama.com/v1 for direct cloud access. Point an OpenAI client’s base URL at the appropriate surface; local clients commonly use any placeholder API key accepted by the SDK, while hosted requests follow Ollama’s bearer-key requirement.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
What the compatibility surface supports
| Capability or field | Documented status |
|---|---|
| Chat completions | Supported in the listed contexts |
| Completions | Supported in the listed contexts |
| Streaming | Supported in the listed contexts |
| JSON mode | Supported in the listed contexts |
| Reproducible outputs | Supported in the listed contexts |
| Vision | Supported in the listed contexts |
| Tools | Supported in the listed contexts |
logprobs |
Unsupported |
| Image URLs | Unsupported |
tool_choice |
Unsupported |
user |
Unsupported |
n |
Unsupported |
/v1/embeddings input |
String or string array accepted; token arrays and dimensions are not accepted in the documented matrix |
The compatibility layer is useful for existing client code, but it is not a complete copy of the full OpenAI API. Check the matrix for your installed Ollama version before porting optional parameters, and switch to the native /api endpoints when you need model lifecycle operations or a native-only field.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesWhat should I verify before putting an Ollama API client in production?
A small amount of explicit state and defensive parsing prevents most integration failures.
- Version: call
GET /api/versionat startup and log the returned version with your deployment. - Model identity: use a pinned
model:tag, record it in logs, and pull it explicitly when a missing-model error occurs. - Response mode: use
stream:falsefor simple request/response code; otherwise parse NDJSON and wait fordone:true. - Timeouts: set an explicit client timeout and expose model-load delays to callers instead of appearing to hang.
- Secrets: keep cloud keys in environment variables or a secret manager and never send them to local-only requests.
- Tools: validate function names and arguments, enforce application authorization, and return results with the exact
toolrole. - Embeddings: preserve input order and store the model and requested dimensions next to each vector.
- Portability: do not assume every OpenAI parameter works through
/v1; test unsupported fields before deployment.
How do I troubleshoot common Ollama API failures?
The server cannot be reached
Confirm that the local Ollama server is running and that the client is calling port 11434. A hosted request should use https://ollama.com/api, include the bearer header, and keep the key out of logs.
The model is missing
Check the installed list with GET /api/tags, compare the exact model:tag spelling, and run an explicit pull before retrying. Avoid relying on an omitted tag when reproducibility matters because omission selects latest.
The client fails to parse the response
Streaming is the default for generation and chat. Parse one JSON object per line, or add "stream": false and read the single completed object.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11The first request is unexpectedly slow
Model loading can occur before generation. Surface that state to users, set a suitable timeout, and use keep_alive when retaining a loaded model is worth the memory cost for your workload.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
A tool call does not appear
Tool support depends on the selected model. Verify support, inspect for a tool_calls field, validate arguments, and be prepared to answer normally when the model does not call a tool.
An OpenAI-client option is rejected
Compare the option with Ollama’s compatibility matrix. Fields such as logprobs, image URLs, tool_choice, user, and n are marked unsupported; use native endpoints or revise the request.
Which interface is better: native /api or OpenAI-compatible /v1?
Choose the native interface when you need Ollama-specific controls and lifecycle operations. Choose /v1 when reducing changes to an existing OpenAI-client integration matters more than complete field coverage.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →| Decision point | Native /api |
OpenAI-compatible /v1 |
|---|---|---|
| Base URL | http://localhost:11434/api or https://ollama.com/api |
http://localhost:11434/v1 or https://ollama.com/v1 |
| Streaming | NDJSON objects with an explicit done:true event |
Use the client’s compatible streaming format, subject to the documented matrix |
| Conversation model | Native messages roles and tool messages |
Chat-completions request shape |
| Embeddings | /api/embed, including native controls such as truncate and supported dimensions |
/v1/embeddings with string or string-array input; token arrays and dimensions are not accepted in the matrix |
| Tool and vision support | Native model-dependent support | Marked supported in the listed compatibility contexts |
| Model management | Pull, push, list, show, create, copy, delete, loaded-model and version endpoints | Use native lifecycle endpoints |
| Authentication | Local calls omit auth; cloud calls use a bearer key | Local SDKs may use a placeholder key; hosted calls still require Ollama’s bearer key |
There are no published official benchmark figures in the API material for latency, throughput, quality, or hardware performance. Select an interface for its capabilities and portability, then measure your own workload.
Frequently Asked Questions
Can the Ollama API work offline?
Yes, a local server can answer requests without a cloud connection once the required model is present on that machine. Cloud endpoints and cloud-hosted models require network access and hosted authentication.
How should I record an Ollama request for reproducibility?
Log the server version, complete model tag, endpoint, prompt or message list, generation options, and whether streaming was enabled. Keeping those values together lets you distinguish a model change from a prompt or client change.
How do I convert Ollama timing fields to milliseconds?
The completed native response reports duration fields in nanoseconds. Divide a value by 1,000,000 to display milliseconds, and label the result as timing for that individual request rather than a benchmark.
Free tools Windows power users keep installed
One-click scans. No signup required.
Can one embedding request contain multiple documents?
Yes. Pass a string array in input; the returned embeddings array follows the same order. Keep each source document associated with its corresponding vector before inserting the batch into your index.
What should I do if a streamed connection closes early?
Treat the response as incomplete unless you received the final object with done:true. Retry according to your application’s idempotency policy, and preserve any request identifier or partial output needed for diagnosis.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
