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 -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 -m pip install openainpm install openaifrom 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].
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.
{
"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:
401means the API key is missing, invalid, expired, or revoked. Load the key from your secret manager and retry after correcting it.402means the credit balance is too low. Add credits in Dashboard → Settings → Credit & Usage.429means the request rate is too high. Apply exponential backoff with jitter and keep the retry count bounded.5xxmeans 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 doctorThe 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
- Authentication explains API keys and control tokens.
- OpenAI migration maps existing SDK settings.
- Model selection compares routing, quality, and cost.
- Media APIs links image, speech, transcription, and video workflows.
- Models lists current model IDs and prices.
UnderSky
UnderSky is a unified AI API gateway for chat, responses, image generation, audio, social media data, and address services. Use one key, one credit balance, and OpenAI-compatible request formats.
Terminal & curl
Discover models with GET /v1/models, call OpenAI-compatible endpoints with curl, stream responses, and use the Python SDK against api.undersky.ai.