API documentation

Documentation

Build against one API.

Lingyuns speaks the OpenAI Chat Completions wire format. Point any SDK at our base URL, swap the key, and you are live in under a minute — no per-provider plumbing, no rewrite when a new model ships.

First request

Everything lives under a single base URL:

Base URL

https://api.lingyuns.com/v1

Authenticate with a bearer token. Keys carry the ly-sk- prefix, are shown exactly once when created, and are stored only as a hash on our side.

Create an account and issue a key from the dashboard.
Load credits — pick a token pack or provision GPU capacity.
Send your first request using one of the snippets below.

Python

The official OpenAI SDK works unmodified. Only base_url changes:

python · chat completion

from openai import OpenAI

client = OpenAI(
    base_url="https://api.lingyuns.com/v1",
    api_key="ly-sk-your-key-here",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Summarise our Q3 rollout plan in three bullets."},
    ],
    temperature=0.3,
)

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

Switch models by changing one string — claude-3-5-sonnet, gemini-1-5-pro, deepseek-r1 and 30+ others are interchangeable.

Node.js

node · chat completion

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.lingyuns.com/v1",
  apiKey: process.env.LINGYUNS_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "claude-3-5-sonnet",
  messages: [{ role: "user", content: "Write a haiku about GPUs." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

cURL

shell · chat completion

curl https://api.lingyuns.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LINGYUNS_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "What is 17 * 24?"}]
  }'

Authentication

Every request carries a bearer token in the Authorization header. Keys are scoped to your account and can be revoked at any time from API Keys.

Authorization: Bearer ly-sk-********************************

Never ship a key in client-side code. Proxy requests through your own backend and keep the key in a server-side environment variable. Revocation takes effect on the next request.

Listing models

Return the same shape as the OpenAI models endpoint, extended with context window and per-million pricing so you can route intelligently at runtime.

shell · list models

curl https://api.lingyuns.com/v1/models \
  -H "Authorization: Bearer $LINGYUNS_API_KEY"

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "owned_by": "OpenAI",
      "context_length": 131072,
      "pricing": { "input": 2.50, "output": 10.00 }
    }
  ]
}

Prices are USD per million tokens. The full catalogue with live pricing is on the models page.

Chat completions

POST https://api.lingyuns.com/v1/chat/completions

Field	Type	Required	Notes
model	string	yes	Any model id from the catalogue.
messages	array	yes	Standard `role`/`content` objects.
temperature	number	no	0–2, default 1.
max_tokens	integer	no	Upper bound on generated tokens.
stream	boolean	no	Server-sent events when true.
tools	array	no	Function calling, supported on flagship and open models.

Streaming

Set "stream": true and consume server-sent events. Each frame is a data: line containing a partial delta, terminated by data: [DONE].

shell · stream

curl -N https://api.lingyuns.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LINGYUNS_API_KEY" \
  -d '{"model":"gpt-4o","stream":true,"messages":[{"role":"user","content":"Count to five."}]}'

Usage accounting is identical for streaming and non-streaming requests — you are billed once per completion, not per frame.

Usage & billing

Credits are denominated in millions of tokens and drawn down as requests complete. Cost per request is computed from the model's input and output rates:

cost = (input_tokens  / 1,000,000) * input_rate
     + (output_tokens / 1,000,000) * output_rate

Example — 40M input and 12M output tokens on GPT-4o ($2.50 in / $10.00 out per million):

(40 * 2.50) + (12 * 10.00) = $220.00  →  drawn from your credit balance

Daily and per-model breakdowns are available in your usage dashboard. GPU rentals are billed separately against the same balance — hourly plans accrue per running hour, monthly reservations commit 720 hours.

Error codes

Status	Type	Meaning	Action
400	invalid_request_error	Malformed body or unknown model id.	Fix the payload.
401	authentication_error	Missing, revoked or malformed key.	Issue a new key.
402	insufficient_credits	Balance exhausted.	Top up a token pack.
429	rate_limit_error	Too many requests for your tier.	Back off and retry.
529	upstream_overloaded	Provider capacity saturated.	Retry or route to a fallback model.

Errors use the standard envelope so existing retry logic keeps working:

{
  "error": {
    "type": "insufficient_credits",
    "message": "Credit balance exhausted. Add credits to continue.",
    "code": 402
  }
}

Rate limits

Limits scale with your committed spend and are enforced per key, per minute.

Tier	Requests / min	Tokens / min	Concurrent streams
Starter	60	200K	8
Growth	300	1M	32
Scale	1,200	4M	128
Enterprise	Custom	Custom	Custom

Need headroom for a launch or a batch job? Talk to us and we will raise your ceiling ahead of time.

Ready to make your first call?

Grab a key, top up credits, and ship.

Get API key View pricing