UnderSky Docs

Quick Start

Create an UnderSky account, generate an API key, top up usage credits, and make your first OpenAI-compatible request with curl, Python, or Node. Continue with streaming, JSON mode, tool calling, media workflows, and production recovery.

This tutorial takes you from a new account to a working API request. You will use the same base URL and API key for text models, images, audio, and social data.

1. Create an account

Sign up from the Dashboard using GitHub or Google.

2. Get an API key

Go to Dashboard → Settings → API Keys and create a key. It starts with sk-.

Store the API key in a secret manager. UnderSky shows the complete key only once.

3. Check the public model list

The model list is public, so you can inspect it before adding credentials:

curl -sS https://api.undersky.ai/v1/models | jq '.data[] | {id, name, pricing}'

Use the model directory for human-readable prices and endpoint links. The pricing page also lists media and data services.

4. Add credits before paid requests

Open Dashboard → Settings → Credit & Usage, add credits, and confirm that the balance is at least $0.10. The gateway checks this minimum before it starts a paid request.

5. Send a chat request

Use auto while you are testing routing, or choose a model such as gpt-6-luna from the public catalog.

curl
curl -sS https://api.undersky.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello from UnderSky!"}]
  }'

The response contains an assistant message in choices[0].message.content and usage fields for billing.

6. Use an SDK

UnderSky accepts the OpenAI client shape. Change the base URL and API key, then keep your existing request code.

Install the SDK for the language you use:

Python
python -m pip install openai
Node.js
npm install openai
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.undersky.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Give me one deployment checklist item."}],
)
print(response.choices[0].message.content)

7. Stream a response

Set stream to true to receive Server-Sent Events. Read each data: line until [DONE].

Streaming curl request
curl -N https://api.undersky.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to three."}]
  }'

See the streaming and chat guide for event parsing and tool calls.

8. Request JSON and tool calls

For a machine-readable answer, send response_format with a JSON schema. For actions, send a tools array and execute the returned function on your server.

JSON response format
{
  "model": "gpt-6-luna",
  "messages": [{"role": "user", "content": "Return the deployment state."}],
  "response_format": {"type": "json_object"}
}

The chat API reference lists the supported request fields and response shape.

9. Generate an image

Image generation is asynchronous. Create a task, then poll its ID or provide a callback URL.

curl -sS https://api.undersky.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A clean abstract cloud over a blue horizon"}'

Follow the image generation guide and image API reference to poll the returned task ID.

10. Handle errors and rate limits

Treat these responses as recoverable or actionable conditions:

  • 401 means the API key is missing, invalid, expired, or revoked. Load the key from your secret manager and retry after correcting it.
  • 402 means the credit balance is too low. Add credits in Dashboard → Settings → Credit & Usage.
  • 429 means the request rate is too high. Apply exponential backoff with jitter and keep the retry count bounded.
  • 5xx means the gateway or upstream failed. Retry idempotent requests, then check API status.

Read the error code reference and rate-limit guide before shipping a retry loop.

11. Check usage and status

Open Dashboard → Settings → Credit & Usage to view balance and recent usage. The public status page shows endpoint and provider availability.

Service integrations can use a control token with the credits:read scope:

curl -sS https://api.undersky.ai/api/v1/credits/balance \
  -H "Authorization: Bearer usc_your-control-token"

12. Check an installed CLI

If you already have undersky-cli installed, run its diagnostics:

undersky-cli doctor

The terminal guide covers CLI availability and more curl examples. You can complete this tutorial with curl or the OpenAI SDK without installing the CLI.

13. Continue with the API reference

On this page