LLM & Image API

Overview

GPUniq provides a single API surface for 90+ language models and image generators across Anthropic, OpenAI, Google, xAI, and DeepSeek. One API key, one balance, one usage dashboard — chat completions, reasoning, and text-to-image all in the same place.

You can use GPUniq LLMs two ways:

1. Native GPUniq API (/v1/llm/*) — wrapped responses, persistent chat sessions, terminal-command generator, SDK helpers.
2. OpenAI-compatible API (/v1/openai/*) — drop-in replacement for api.openai.com/v1. Works with Claude Code, Cursor, Continue.dev, Aider, LiteLLM, and the official OpenAI Python/JS SDKs without code changes.

Available Models

Chat & Reasoning

DeepSeek pricing (USD per 1M tokens, already discounted −20%)

MiniMax pricing (USD per 1M tokens)

Image Generation

Image models are billed per returned image, not per token.

Job-based image generation (recommended)

POST /v1/llm/images/jobs returns a job_id in under a second, and you poll GET /v1/llm/images/jobs/{job_id} every 2-3 seconds until the status is terminal. You are charged only when the completion poll returns — a timed-out or failed job costs nothing. Server-side, polls that arrive within 2 seconds of each other are coalesced via Redis, so hammering the endpoint will not be billed as repeated upstream calls.

import time, requests

BASE = "https://api.gpuniq.com/v1/llm"
HEADERS = {"X-API-Key": "gpuniq_your_key"}

# 1. Kickoff
start = requests.post(
    f"{BASE}/images/jobs",
    headers=HEADERS,
    json={"model": "nano-banana-pro", "prompt": "a cozy cabin at sunrise", "n": 1},
).json()
job_id = start["data"]["job_id"]

# 2. Poll — 5-minute budget covers the slowest Pro / 4K runs
deadline = time.time() + 300
while time.time() < deadline:
    time.sleep(2.5)
    r = requests.get(f"{BASE}/images/jobs/{job_id}", headers=HEADERS).json()
    d = r["data"]
    if d["status"] == "completed":
        image_b64 = d["image"]["b64_json"]
        print(f"Cost: ${d['cost_usd']}, balance: ${d['balance_usd']}")
        break
    if d["status"] == "failed":
        print("failed:", d.get("error"))
        break

Only Nano Banana slugs are accepted on this surface. n must be 1 — issue separate jobs in parallel for batches.

Generating an image inside a chat session

When you want the image to appear as a turn in an existing chat (so the prompt and result both land in the chat history), POST to /v1/llm/chats/{chat_id}/messages with an image model. The response returns immediately with type: "image_pending" plus a job_id and the dialogue_id of a placeholder row that already lives in the chat history. Poll GET /v1/llm/chats/{chat_id}/image-jobs/{job_id} until the status is completed (placeholder is rewritten with the image and the balance is debited) or failed (placeholder is marked, nothing charged). The polling endpoint 404s once the job is terminal — the final dialogue is the source of truth from then on.

import time, requests

BASE = "https://api.gpuniq.com/v1/llm"
HEADERS = {"X-API-Key": "gpuniq_your_key"}
chat_id = 42  # existing chat created via POST /v1/llm/chats

# 1. Kickoff (POST /chats/{id}/messages with an image model)
start = requests.post(
    f"{BASE}/chats/{chat_id}/messages",
    headers=HEADERS,
    json={"model": "nano-banana-pro", "message": "a cozy cabin at sunrise"},
).json()
job_id = start["data"]["job_id"]
dialogue_id = start["data"]["dialogue_id"]

# 2. Poll — same 5-minute budget as the standalone /images/jobs flow
deadline = time.time() + 300
while time.time() < deadline:
    time.sleep(2.5)
    r = requests.get(
        f"{BASE}/chats/{chat_id}/image-jobs/{job_id}", headers=HEADERS,
    ).json()
    d = r["data"]
    if d["status"] == "completed":
        image_b64 = d["image"]["b64_json"]
        print(f"Cost: ${d['cost_usd']}, balance: ${d['balance_usd']}")
        break
    if d["status"] == "failed":
        print("failed:", d.get("error"))
        break

Use this surface when the image should be part of a multi-turn conversation. Use the standalone /images/jobs surface when you don't need persistence — it has the same job semantics without creating a chat row.

Video Generation

Video models are billed per delivered video, not per token. Every generation is asynchronous — POST to /v1/llm/videos/jobs to kick off a job, then poll GET /v1/llm/videos/jobs/{job_id} until the status is terminal. You are charged only when the completion poll returns a video.url — a failed or timed-out job costs nothing.

Job-based video generation

Same kickoff-then-poll shape as the image-jobs API. The catalog covers text-to-video (t2v), image-to-video (i2v, pass image_url), and video-to-video / motion-control (v2v, pass video_url + image_url for the conditioning frame). Avatar SKUs accept an audio reference URL in the prompt body — see the model-specific docs for the schema.

import time, requests

BASE = "https://api.gpuniq.com/v1/llm"
HEADERS = {"X-API-Key": "gpuniq_your_key"}

# 1. Kickoff
start = requests.post(
    f"{BASE}/videos/jobs",
    headers=HEADERS,
    json={
        "model": "kling-2-6",
        "prompt": "A small black cat slowly turns toward the camera at golden hour",
        "duration": 5,
        "audio": False,          # opt-in, doubles price on Kling 2.6 / 3.0
        "resolution": "1080p",   # 720p | 1080p | 4k (where supported)
    },
).json()
job_id = start["data"]["job_id"]
print(f"job: {job_id}, est cost: ${start['data']['estimated_cost_usd']}")

# 2. Poll — video models deliver in 30-90s; budget 5 minutes for the slowest variants
deadline = time.time() + 300
while time.time() < deadline:
    time.sleep(3)
    r = requests.get(f"{BASE}/videos/jobs/{job_id}", headers=HEADERS).json()
    d = r["data"]
    if d["status"] == "completed":
        print(f"video: {d['video']['url']}")
        print(f"cost: ${d['cost_usd']}, balance: ${d['balance_usd']}")
        break
    if d["status"] == "failed":
        print("failed:", d.get("error"))
        break

Request body

Response

The kickoff returns immediately with the GPUniq job id, the resolved parameter snapshot, and the cost estimate. Internal routing is opaque — the same job_id is valid across fallbacks, and the user-facing price stays stable.

// POST /v1/llm/videos/jobs
{
  "job_id": "vid_e93e98c7ca5e4982876b",
  "status": "pending",
  "model": "kling-2-6",
  "estimated_cost_usd": 0.315,
  "config": { "resolution": "1080p", "audio": false, "duration": 5, "task": "t2v", "mode": null }
}

// GET /v1/llm/videos/jobs/{job_id} — completed
{
  "job_id": "vid_e93e98c7ca5e4982876b",
  "status": "completed",
  "model": "kling-2-6",
  "video": { "url": "https://cdn.example.com/.../output.mp4" },
  "cost_usd": 0.315,
  "balance_usd": 9.17825791,
  "config": { "resolution": "1080p", "audio": false, "duration": 5, "task": "t2v", "mode": null }
}

The polling endpoint transparently falls back across internal routes if the first attempt fails — your job_id and the user-facing price stay stable across fallbacks. Internal route identifiers are deliberately omitted from the public response; they live only in admin/operator logs.

Chat models are sold at 20% below vendor list price.

Fetch the live catalog at any time:

models = client.llm.models()
for model in models["models"]:
    print(model)

curl https://api.gpuniq.com/v1/llm/models/catalog

curl https://api.gpuniq.com/v1/openai/models \
  -H "Authorization: Bearer gpuniq_your_key"

The default model is claude-haiku-4-5 — fast, cheap, strong at code.

Long generations & streaming

The edge proxy closes inbound connections after ~100 seconds of streaming silence. A non-streaming request asking for max_tokens > 4096 is rejected up-front with HTTP 400 streaming_required — buffered responses past that length routinely lose to the cap. For long replies, set "stream": true or use the job-based long-poll API.

Reasoning models (Gemini 3 Pro, DeepSeek R1, o3, Claude Opus thinking) burn tokens on hidden chain-of-thought before the visible reply, so they need extra max_tokens headroom — see the Long generations guide for the full streaming / job-based / reasoning-token recipe.

Errors

Every failure returns a stable OpenAI error envelope with a structured code you can branch on — streaming_required, insufficient_balance, model_not_found, rate_limit_per_key, etc. See the Error reference for the complete catalog (29 codes), recovery strategies, and the native vs. OpenAI-compat envelope shapes.

{
  "error": {
    "message": "…human-readable description…",
    "type": "invalid_request_error",
    "code": "streaming_required",
    "doc_url": "https://docs.gpuniq.com/llm/long-generations",
    "meta": { "max_tokens": 8000, "limit": 4096 }
  },
  "status_code": 400,
  "request_id": "…"
}

OpenAI-Compatible Endpoint

Point any OpenAI-compatible tool at GPUniq by setting two environment variables:

OPENAI_API_KEY=gpuniq_your_key
OPENAI_BASE_URL=https://api.gpuniq.com/v1/openai

Every field of the OpenAI Chat Completions protocol is forwarded unchanged: tools, tool_choice, response_format, logprobs, seed, stream, stream_options, etc.

Official OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="gpuniq_your_key",
    base_url="https://api.gpuniq.com/v1/openai",
)

resp = client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Write a binary search in Rust."}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "gpuniq_your_key",
  baseURL: "https://api.gpuniq.com/v1/openai",
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-7",
  messages: [{ role: "user", content: "Write a binary search in Rust." }],
});
console.log(resp.choices[0].message.content);

curl https://api.gpuniq.com/v1/openai/chat/completions \
  -H "Authorization: Bearer gpuniq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [{"role": "user", "content": "Write a binary search in Rust."}]
  }'

Streaming

Set stream: true — GPUniq returns a text/event-stream with byte-identical OpenAI SSE framing:

stream = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Explain MoE in one paragraph."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Image Generation

Both API surfaces expose a /images/generations endpoint that matches OpenAI's images.generate protocol. Pass any image slug from the catalog above (e.g. nano-banana-pro, gpt-image-2, flux-2-pro, seedream-4). Billing is flat per returned image — no token accounting.

Image requests route through a multi-tier reliability chain behind the scenes: a per-model priority gateway, two cost-optimised intermediaries, then a generic OpenAI-compatible fallback for safety. The chain is selected automatically per slug, so SDK callers never pick a backend themselves. If the primary fails or returns no image, the next tier is tried within the same HTTP request — you still see one synchronous POST /images/generations and pay for delivered images only.

Heavy generations (Pro / 4K, multi-image batches, high-quality preset) can run up to 5 minutes end-to-end; the connection is held open for that whole budget so SDKs never need to re-poll. For interactive UIs that cannot keep an HTTP connection open that long, prefer the job-based API.

from openai import OpenAI

client = OpenAI(
    api_key="gpuniq_your_key",
    base_url="https://api.gpuniq.com/v1/openai",
)

resp = client.images.generate(
    model="nano-banana-pro",
    prompt="A cozy mountain cabin at sunrise, cinematic lighting",
    n=2,
    size="1024x1024",
    response_format="b64_json",
)

for i, img in enumerate(resp.data):
    with open(f"out_{i}.png", "wb") as f:
        import base64
        f.write(base64.b64decode(img.b64_json))

import base64, requests

with open("reference.jpg", "rb") as fh:
    ref = "data:image/jpeg;base64," + base64.b64encode(fh.read()).decode()

resp = requests.post(
    "https://api.gpuniq.com/v1/llm/images/generations",
    headers={"X-API-Key": "gpuniq_your_key"},
    json={
        "model": "nano-banana-pro",
        "prompt": "Redraw the cabin in watercolor style",
        "n": 1,
        "size": "2048x2048",
        "input_images": [ref],
    },
).json()

print("cost:", resp["data"]["cost_usd"])

curl -X POST https://api.gpuniq.com/v1/openai/images/generations \
  -H "Authorization: Bearer gpuniq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4-image",
    "prompt": "Studio portrait of an astronaut in a pink desert",
    "n": 1,
    "size": "1024x1024"
  }'

Parameters

Claude Code

Claude Code can route through GPUniq via a LiteLLM proxy. Run LiteLLM locally as an Anthropic-compatible front-end for the GPUniq OpenAI endpoint:

# ~/litellm.yaml
model_list:
  - model_name: claude-opus-4-7
    litellm_params:
      model: openai/claude-opus-4-7
      api_base: https://api.gpuniq.com/v1/openai
      api_key: os.environ/GPUNIQ_API_KEY

export GPUNIQ_API_KEY=gpuniq_your_key
litellm --config ~/litellm.yaml --port 4000

# In another shell — point Claude Code at the proxy
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=sk-litellm-anything
claude

All tokens are billed against your GPUniq balance — no separate Anthropic account required.

Cursor

Settings → Models → Override OpenAI Base URL:

Base URL:  https://api.gpuniq.com/v1/openai
API Key:   gpuniq_your_key
Model:     claude-opus-4-7   # or any slug from /v1/openai/models

Continue.dev / Aider / LiteLLM

Any tool that accepts an OPENAI_BASE_URL works the same way:

export OPENAI_API_KEY=gpuniq_your_key
export OPENAI_BASE_URL=https://api.gpuniq.com/v1/openai

aider --model claude-sonnet-4-6

Native GPUniq SDK

For the fullest feature set — persistent chat sessions, USD balance conversion, usage history — use the native API.

Simple Chat

response = client.llm.chat("claude-haiku-4-5", "Explain how transformers work")
print(response)

curl -X POST "https://api.gpuniq.com/v1/llm/chat/completions" \
  -H "X-API-Key: gpuniq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Explain how transformers work"}],
    "model": "claude-haiku-4-5"
  }'

Chat Completion (Full)

data = client.llm.chat_completion(
    messages=[
        {"role": "system", "content": "You are a helpful AI assistant."},
        {"role": "user", "content": "What is gradient descent?"},
    ],
    model="claude-sonnet-4-6",
    temperature=0.7,
    max_tokens=1000,
    top_p=0.9,
)

print(data["content"])
print(f"Tokens used: {data['tokens_used']}  cost: ${data['cost_usd']:.6f}")

Parameters

Account Balance

Chat and image requests are billed directly against your GPUniq account balance in USD — there is no separate "token pool" anymore. Each call deducts the model's blended retail rate × the tokens it actually consumed (or per-image flat rate for image models). Prepaid token packages and ruble-to-token conversions are no longer required and the corresponding endpoints have been retired.

balance = client.llm.balance()
print(f"Available: ${balance['balance_usd']:.4f} USD")

curl https://api.gpuniq.com/v1/llm/balance \
  -H "Authorization: Bearer gpuniq_your_key"

Top up the balance from the web dashboard → Billing (Stripe / YooKassa / crypto). The balance is shared with every other GPUniq surface — GPU rentals, volume storage, image generations — so a single deposit covers the whole platform.

Usage History

Per-request detail with prompt / completion / cached / reasoning tokens and the USD cost charged at retail. Backed by the /v1/llm/usage/history endpoint; pair it with /v1/llm/usage/breakdown for daily / weekly aggregates.

history = client.llm.usage_history(limit=50, offset=0)
for log in history["logs"]:
    print(f"{log['model']}: {log['total_tokens']} tokens — ${log['cost_usd']:.6f}")

Chat Sessions

Persistent conversations stored server-side — the model sees the full history on every call:

# Create a session
session = client.llm.create_chat_session(
    model="claude-sonnet-4-6",
    title="Research Assistant",
)

# Send messages within the session
reply = client.llm.send_message(
    chat_id=session["id"],
    message="What are the key papers on attention mechanisms?",
    temperature=0.5,
)

# List all sessions
sessions = client.llm.list_chat_sessions(limit=50)

# Get a session with full message history
full = client.llm.get_chat_session(chat_id=session["id"])

# Update title
client.llm.update_chat_session(chat_id=session["id"], title="New Title")

# Delete
client.llm.delete_chat_session(chat_id=session["id"])

Generate Terminal Commands

Convert natural language to a ranked list of shell commands with danger annotations:

cmds = client.llm.generate_commands(
    prompt="find all Python files larger than 1MB and sort by size",
    max_commands=5,
)
for c in cmds["commands"]:
    print(f"[{c['danger']}] {c['command']}  # {c['description']}")

API Key Management

API keys are created from the web dashboard (LLM API Keys) and sent as Authorization: Bearer gpuniq_... on OpenAI-compat routes, or X-API-Key: gpuniq_... on native routes.

Rate limit: 120 req/min per key, sliding window.