API Reference

GptGet API documentation

One OpenAI-compatible endpoint for 500+ models across every modality — chat, vision, embeddings, image, audio, video and realtime. Point your existing OpenAI, Anthropic, or Gemini SDK at GptGet and our gateway handles smart multi-provider routing and health-based failover.

Get an API key·Browse model catalog

Getting Started

Introduction Authentication Models & routing

Core APIs

Chat Completions Responses API Anthropic Messages Google Gemini Embeddings

Media

Image generation Text-to-Speech Transcription Video generation Async Tasks

Computers

Overview & quickstart Control & actions Computer-use agent Python SDK & CLI

Realtime & Streaming

Realtime (WebSocket)Streaming

Reference

Credits & usage Errors & status codes

Introduction & Quickstart

The GptGet API is OpenAI-compatible. The base URL for all standard requests is below; a Gemini-native surface is also exposed under /v1beta.

POSThttps://api.gptget.net/v1— OpenAI-compatible base

POSThttps://api.gptget.net/v1beta— Gemini-native base

Your first chat request with cURL:

bash

curl https://api.gptget.net/v1/chat/completions \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      { "role": "user", "content": "Explain quantum computing in one sentence." }
    ]
  }'

Drop-in with the OpenAI SDK — just change base_url. Install with pip install openai:

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-getgpt-...",
    base_url="https://api.gptget.net/v1",
)

resp = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

Same idea in JavaScript (npm install openai):

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GPTGET_API_KEY,
  baseURL: "https://api.gptget.net/v1",
});

const completion = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(completion.choices[0].message.content);

Authentication

Every request must be authenticated with a developer key that starts with sk-getgpt-. The standard form is an Authorization: Bearer header. For native compatibility, the gateway also accepts the Anthropic and Gemini header forms:

http

# Standard (OpenAI-style)
Authorization: Bearer sk-getgpt-...

# Anthropic-style
x-api-key: sk-getgpt-...

# Gemini-native style
x-goog-api-key: sk-getgpt-...

Create and manage your keys at /keys. Treat keys like passwords — never commit them to source control or expose them in client-side code.

Models & routing

Model ids use a provider/model namespace, for example openai/gpt-4o, anthropic/claude-sonnet-4, google/gemini-2.5-pro, and x-ai/grok-2. The gateway performs smart multi-provider routing with health-based failover, so a single id can be served by whichever upstream is healthiest.

GET/v1/models— List available models

GET/v1/models/{id}— Retrieve one model

bash

curl https://api.gptget.net/v1/models \
  -H "Authorization: Bearer $GPTGET_API_KEY"

# Retrieve a single model
curl https://api.gptget.net/v1/models/openai/gpt-4o \
  -H "Authorization: Bearer $GPTGET_API_KEY"

json

{
  "object": "list",
  "data": [
    { "id": "openai/gpt-4o", "object": "model", "owned_by": "openai" },
    { "id": "anthropic/claude-sonnet-4", "object": "model", "owned_by": "anthropic" },
    { "id": "google/gemini-2.5-pro", "object": "model", "owned_by": "google" },
    { "id": "x-ai/grok-2", "object": "model", "owned_by": "x-ai" }
  ]
}

Browse the full catalog, pricing, and capabilities at /pricing.

Chat Completions

POST/v1/chat/completions

The primary, fully OpenAI-compatible endpoint. Send a list of messages and receive a completion.

bash

curl https://api.gptget.net/v1/chat/completions \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Name three primary colors." }
    ],
    "temperature": 0.7
  }'

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "anthropic/claude-sonnet-4",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Red, blue, and yellow." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 7, "total_tokens": 28 }
}

Set "stream": true for an SSE token stream (see Streaming):

bash

curl https://api.gptget.net/v1/chat/completions \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "stream": true,
    "messages": [{ "role": "user", "content": "Write a haiku about the sea." }]
  }'

Tools / function calling. Pass a tools array; the model may respond with tool_calls you execute and feed back as a role: "tool" message.

json

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "What is the weather in Paris?" }],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Vision & JSON mode. Send image parts via image_url content blocks, and force valid JSON with response_format.

json

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What is in this image?" },
        { "type": "image_url", "image_url": { "url": "https://example.com/cat.jpg" } }
      ]
    }
  ],
  "response_format": { "type": "json_object" }
}

Responses API

POST/v1/responses

OpenAI's Responses API. Provide an input (string or structured content) and read the convenience field output_text, or the full output array.

bash

curl https://api.gptget.net/v1/responses \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Write a one-line bedtime story about a robot."
  }'

json

{
  "id": "resp_abc123",
  "object": "response",
  "model": "openai/gpt-4o",
  "output_text": "The little robot dreamed in soft blue circuits until morning.",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "The little robot dreamed..." }]
    }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 16, "total_tokens": 30 }
}

Anthropic Messages (native)

POST/v1/messages

The native Anthropic Messages surface. Authenticate with x-api-key and send the anthropic-version: 2023-06-01 header. The body requires model, max_tokens, and messages; the response returns a content array of typed blocks.

bash

curl https://api.gptget.net/v1/messages \
  -H "x-api-key: $GPTGET_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "Hello, Claude!" }
    ]
  }'

json

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-4",
  "content": [
    { "type": "text", "text": "Hello! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 10, "output_tokens": 12 }
}

Google Gemini (native)

POST/v1beta/models/{model}:generateContent

POST/v1beta/models/{model}:streamGenerateContent

The native Gemini surface under /v1beta. Authenticate with x-goog-api-key. Send contents with parts; the response returns candidates plus usageMetadata.

bash

curl "https://api.gptget.net/v1beta/models/google/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "parts": [{ "text": "Write a haiku about autumn." }] }
    ]
  }'

json

{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "Crisp leaves drift downward / ..." }],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 17,
    "totalTokenCount": 25
  }
}

Use the streaming method for incremental output:

bash

# Server-sent events variant
curl "https://api.gptget.net/v1beta/models/google/gemini-2.5-pro:streamGenerateContent" \
  -H "x-goog-api-key: $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contents": [{ "parts": [{ "text": "Tell me a story." }] }] }'

Embeddings

POST/v1/embeddings

Generate vector embeddings for text. Pass model and input (a string or array of strings); receive a data array of embedding vectors.

bash

curl https://api.gptget.net/v1/embeddings \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "The quick brown fox."
  }'

json

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.0143, 0.0388, "..."] }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": { "prompt_tokens": 5, "total_tokens": 5 }
}

Image generation

POST/v1/images/generations

Generate images from a prompt. Pass model, prompt, n, and size.

bash

curl https://api.gptget.net/v1/images/generations \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "A watercolor fox in a misty forest",
    "n": 1,
    "size": "1024x1024"
  }'

json

{
  "created": 1730000000,
  "data": [
    { "url": "https://api.gptget.net/v1/images/img_abc123/content?index=0" }
  ]
}

Note. The returned url is GptGet's own authenticated content-proxy URL — never the upstream provider URL. It requires your key to fetch.

Audio — Text-to-Speech

POST/v1/audio/speech

Synthesize speech from text. Pass model, input, voice, and response_format. The response is raw audio bytes.

bash

curl https://api.gptget.net/v1/audio/speech \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/tts-1",
    "input": "Hello from GptGet!",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Audio — Transcription

POST/v1/audio/transcriptions

Transcribe audio to text. Upload a file (multipart) or pass input_audio; receive { text }.

bash

curl https://api.gptget.net/v1/audio/transcriptions \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -F model="openai/whisper-1" \
  -F file="@audio.mp3"

json

{ "text": "Hello from GptGet, this is the transcribed audio." }

Video generation (async)

POST/v1/video/generations— Create task

GET/v1/videos/{id}— Poll status

GET/v1/videos/{id}/content?index=0— Fetch result

Video generation is asynchronous. Creating a job returns a task with an id; poll GET /v1/videos/{id} until status is completed. The finished result.url is an authenticated proxy endpoint.

bash

# 1. Create the task
curl https://api.gptget.net/v1/video/generations \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3",
    "prompt": "A drone shot over a neon city at night"
  }'
# -> { "id": "vid_abc123", "status": "queued" }

# 2. Poll until complete
curl https://api.gptget.net/v1/videos/vid_abc123 \
  -H "Authorization: Bearer $GPTGET_API_KEY"

json

{
  "id": "vid_abc123",
  "status": "completed",
  "result": {
    "url": "https://api.gptget.net/v1/videos/vid_abc123/content?index=0"
  }
}

Async Tasks (image / video / music / mj / suno)

POST/v1/tasks— Create task

GET/v1/tasks— List tasks

GET/v1/tasks/{id}— Poll task

A unified async surface for long-running generation across modalities (image, video, music, Midjourney, Suno). Submit a { type, model, ... } body, then poll. Results are exposed only as authenticated proxy URLs of the form /v1/{videos|images|audio}/{id}/content?index=N.

bash

# Create an async task
curl https://api.gptget.net/v1/tasks \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "google/veo-3",
    "prompt": "A timelapse of a blooming flower"
  }'

# List tasks
curl https://api.gptget.net/v1/tasks \
  -H "Authorization: Bearer $GPTGET_API_KEY"

# Poll a single task
curl https://api.gptget.net/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $GPTGET_API_KEY"

json

{
  "id": "task_abc123",
  "type": "video",
  "status": "completed",
  "result": {
    "url": "https://api.gptget.net/v1/videos/task_abc123/content?index=0"
  }
}

Computers — overview & quickstart

GptGet Computers are cloud Linux desktops (full X11 + browser) that an AI agent can see and control. Create one with a single call, then drive it over REST, the Python SDK / CLI, or hand it to a computer-use model. Same sk- key and wallet as the rest of the API.

POST2c2g — $0.0139/hr— 2 vCPU · 2 GB

POST2c4g — $0.0208/hr— 2 vCPU · 4 GB

POST4c8g — $0.0403/hr— 4 vCPU · 8 GB

Billing is per running hour (partial hours rounded up); stopped computers don't accrue compute. Regions: us, fr.

bash

# 1. create a workspace (a project namespace for your computers)
curl https://api.gptget.net/v1/workspaces \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -d '{"name":"my-project"}'
# → { "id": "ws_...", "name": "my-project" }

# 2. launch a cloud Linux desktop in it
curl https://api.gptget.net/v1/computers \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -d '{"workspace_id":"ws_...","name":"box-1","instance_type":"2c4g","region":"us"}'

json

{
  "id": "cb4b46ce-ba7d-437c-bc7a-6dda6abfad9a",
  "instance_id": "ea5fdeeb",
  "name": "box-1",
  "instance_type": "2c4g",
  "cpu": 2, "ram": 4, "disk_size_gb": 8,
  "status": "running",
  "region": "us",
  "hostname": "us1-cu.gptget.net",
  "connection_url": "https://us1-cu.gptget.net/i/ea5fdeeb/vnc.html?autoconnect=1&..."
}

Open connection_url in a browser for a live, interactive view of the desktop (noVNC). The console's Computers page gives you the same split-view with an agent chat beside it.

Computers — control & actions

GET/v1/computers— list

GET/v1/computers/{id}— get one

GET/v1/computers/{id}/screenshot— base64 PNG

POST/v1/computers/{id}/click · /type · /key · /scroll · /drag— input

POST/v1/computers/{id}/bash— shell inside the desktop

POST/v1/computers/{id}/start · /stop · /restart— lifecycle

DELETE/v1/computers/{id}— destroy

bash

ID=cb4b46ce-ba7d-437c-bc7a-6dda6abfad9a          # the computer id
H="Authorization: Bearer $GPTGET_API_KEY"

# capture the screen → { "image": "<base64 png>" }
curl https://api.gptget.net/v1/computers/$ID/screenshot -H "$H"

# mouse + keyboard
curl https://api.gptget.net/v1/computers/$ID/click  -H "$H" -d '{"x":420,"y":300,"button":"left"}'
curl https://api.gptget.net/v1/computers/$ID/type   -H "$H" -d '{"text":"hello world"}'
curl https://api.gptget.net/v1/computers/$ID/key    -H "$H" -d '{"key":"Return"}'
curl https://api.gptget.net/v1/computers/$ID/scroll -H "$H" -d '{"direction":"down","amount":3}'

# run a shell command inside the desktop
curl https://api.gptget.net/v1/computers/$ID/bash   -H "$H" -d '{"command":"ls ~"}'

# lifecycle
curl -XPOST   https://api.gptget.net/v1/computers/$ID/stop    -H "$H"
curl -XPOST   https://api.gptget.net/v1/computers/$ID/start   -H "$H"
curl -XDELETE https://api.gptget.net/v1/computers/$ID         -H "$H"

Computer-use agent

POST/v1/chat/completions— add a computer_id

Add a computer_id to a normal Chat Completions request and the model runs a computer-use loop — it screenshots the desktop, decides an action, executes it, and repeats up to max_steps. Set "stream": true for a live token + action stream. Bills the model's tokens plus the computer's runtime.

bash

# Hand a computer to a computer-use model. It screenshots, clicks and types
# on its own until the task is done — driven by the standard chat endpoint,
# just add "computer_id". Set "stream": true for an SSE token + action stream.
curl https://api.gptget.net/v1/chat/completions \
  -H "Authorization: Bearer $GPTGET_API_KEY" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "computer_id": "cb4b46ce-ba7d-437c-bc7a-6dda6abfad9a",
    "max_steps": 25,
    "messages": [{"role":"user","content":"Open Firefox and search for hermes bags"}]
  }'

Computer-use models. Anthropic's tool support is per-model — current picks: anthropic/claude-sonnet-4.5, anthropic/claude-opus-4.1, anthropic/claude-opus-4.5. The console picker lists exactly the supported models.

Python SDK & CLI

Python. The gptget package wraps the API in a Computer object.

bash

pip install gptget

python

from gptget import Computer

# launches a cloud desktop (GPTGET_API_KEY from the environment)
computer = Computer(instance_type="2c4g", region="us")

# drive it directly
computer.left_click(420, 300)
computer.type("hello world")
computer.key("Return")
print(computer.bash("uname -a"))
img = computer.screenshot()             # PNG bytes

# …or let a computer-use model drive it
computer.prompt("Open Firefox and search for hermes bags",
                model="anthropic/claude-sonnet-4.5")

computer.destroy()

CLI. Manage computers from the terminal with the gptget npm package.

bash

npm i -g gptget
gptget login                                  # platform OAuth (device code)
gptget computers create --type 2c4g --region us
gptget computers                              # list
gptget screenshot <id> shot.png
gptget run <id> "open a terminal and run htop" --model anthropic/claude-sonnet-4.5
gptget stop <id>
gptget delete <id>

Realtime (WebSocket)

WSwss://api.gptget.net/v1/realtime?model=openai/gpt-realtime

Connect over WebSocket and speak the OpenAI Realtime event protocol — session.update, conversation.item.create, response.create, and streamed events like response.output_audio.delta. Authenticate with a Bearer subprotocol or an api_key query parameter.

javascript

const ws = new WebSocket(
  "wss://api.gptget.net/v1/realtime?model=openai/gpt-realtime",
  // Auth via subprotocol (or pass ?api_key=sk-getgpt-... in the query)
  ["openai-realtime", "openai-insecure-api-key.sk-getgpt-..."]
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: { modalities: ["text", "audio"], voice: "alloy" }
  }));
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: { type: "message", role: "user",
      content: [{ type: "input_text", text: "Hi there!" }] }
  }));
  ws.send(JSON.stringify({ type: "response.create" }));
};

ws.onmessage = (ev) => {
  const event = JSON.parse(ev.data);
  if (event.type === "response.output_audio.delta") {
    // base64 PCM audio chunk in event.delta
  }
};

Streaming

With "stream": true, responses are delivered as Server-Sent Events. Each event is a line data: {json chunk} separated by a blank line, and the stream terminates with data: [DONE].

text

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

Most SDKs parse this for you — for example with the OpenAI Python SDK:

python

from openai import OpenAI
client = OpenAI(api_key="sk-getgpt-...", base_url="https://api.gptget.net/v1")

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Count to 5."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Credits & usage

GET/v1/credits— Remaining balance

GET/v1/generation— Cost of one generation

Check your remaining balance, and look up the token usage and cost of an individual generation by id.

bash

# Remaining balance
curl https://api.gptget.net/v1/credits \
  -H "Authorization: Bearer $GPTGET_API_KEY"

# Look up usage/cost for a single generation
curl "https://api.gptget.net/v1/generation?id=chatcmpl-abc123" \
  -H "Authorization: Bearer $GPTGET_API_KEY"

json

{
  "data": {
    "total_credits": 50.0,
    "total_usage": 12.34
  }
}

Errors & status codes

Errors use an OpenAI-style envelope. The HTTP status mirrors the error.code field.

json

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": 401
  }
}

Code	Type	Meaning
200	OK	Request succeeded.
400	invalid_request_error	Malformed request or invalid parameters.
401	authentication_error	Missing or invalid API key.
402	insufficient_credits	Not enough credits to complete the request.
403	permission_error	Key lacks permission for this model or action.
404	not_found_error	Model, task, or resource does not exist.
429	rate_limit_error	Too many requests — slow down and retry.
5xx	api_error	Upstream provider or gateway error — safe to retry.