---
name: novitaai
description: Use when building AI applications with hosted LLM APIs, running
  code in isolated agent sandboxes, deploying GPU instances, or integrating
  multimodal AI models. Reach for this skill when users need to call language
  models, run agents in sandboxes, manage GPU compute, or troubleshoot API
  errors.
metadata:
  mintlify-proj: novitaai
  version: "1.0"
---

# Novita AI Skill

## Product Summary

Novita AI is a platform providing hosted AI model APIs (LLMs, image/audio generation), isolated sandbox environments for agents, and GPU infrastructure. Agents use it to call OpenAI-compatible LLM endpoints, run code in managed sandboxes, deploy GPU instances, or access multimodal AI capabilities. The primary API endpoint is `https://api.novita.ai/openai` for LLMs and `https://api.novita.ai` for other services. Authentication uses Bearer tokens via the `Authorization: Bearer <API_KEY>` header. Key files: API keys are managed at `https://novita.ai/settings/key-management`, billing at `https://novita.ai/billing`. See the full documentation at https://docs.novita.ai.

## When to Use

Reach for this skill when:
- **Building LLM applications**: User asks to call language models, generate text, or integrate AI into an app. Use the OpenAI-compatible chat/completion endpoints.
- **Running agent code**: User needs an isolated environment to execute code, install packages, or run browser automation. Use Novita Sandbox.
- **GPU compute**: User wants to deploy models on dedicated GPUs or use serverless GPU endpoints for inference.
- **Multimodal AI**: User needs image generation, audio synthesis, or video generation APIs.
- **Batch processing**: User has large-scale inference jobs that don't need immediate results. Use the Batch API.
- **Troubleshooting API errors**: User encounters 401, 403, 429, 503, or 500 errors. Diagnose using error codes and rate limits.
- **Managing API keys**: User needs to create, restrict, or configure API key access policies.

## Quick Reference

### API Endpoints

| Service | Base URL | Purpose |
|---------|----------|---------|
| LLM (OpenAI-compatible) | `https://api.novita.ai/openai` | Chat completions, embeddings, batch jobs |
| Core APIs | `https://api.novita.ai` | GPU instances, billing, account management |
| Sandbox | `us-phx-1.sandbox.novita.ai` (v2, default) | Agent execution environments |

### Authentication

```bash
# Bearer token in Authorization header
Authorization: Bearer sk_<your_api_key>

# Environment variable (recommended)
export NOVITA_API_KEY="sk_<your_api_key>"
```

### Common LLM Models

| Model | Use Case | Cost |
|-------|----------|------|
| `deepseek/deepseek-v4.1-flash` | Fast, general-purpose | Low |
| `deepseek/deepseek-r1-0528` | Reasoning, complex tasks | Medium |
| `claude-3.5-sonnet` | High-quality output | Medium-High |
| `gpt-4o` | Advanced reasoning | High |

### Essential Commands

**List available models:**
```bash
curl https://api.novita.ai/openai/v1/models \
  -H "Authorization: Bearer $NOVITA_API_KEY"
```

**Send a chat completion request:**
```bash
curl https://api.novita.ai/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 512
  }'
```

**Check account balance:**
```bash
curl https://api.novita.ai/user/balance \
  -H "Authorization: Bearer $NOVITA_API_KEY"
```

### SDK Setup (Python)

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key="sk_<your_api_key>"
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=512
)
print(response.choices[0].message.content)
```

## Decision Guidance

### When to Use X vs Y

| Scenario | Use This | Why |
|----------|----------|-----|
| **Real-time response needed** | Chat/Completion API (streaming) | Immediate results, lower latency |
| **Large batch of requests** | Batch API | 24-hour window, higher rate limits, cost-effective |
| **Need code execution** | Novita Sandbox | Isolated environment, persistent state, file access |
| **Long-running inference** | GPU Instance | Dedicated hardware, full control, predictable costs |
| **Sporadic GPU workloads** | Serverless GPUs | Pay-per-use, auto-scaling, no idle costs |
| **Restrict model access** | Model Access Policy | Limit key to specific models, prevent cost overruns |
| **Streaming vs non-streaming** | Streaming for long outputs | Prevents timeout, returns tokens as generated |

### API Key Access Modes

| Mode | Use Case | Behavior |
|------|----------|----------|
| All enabled models (default) | General development | Key can call any model team has enabled; future models auto-included |
| Selected models only | Production/cost control | Key restricted to specific models; new models require manual addition |

## Workflow

### 1. Set Up Authentication
- Create an API key at https://novita.ai/settings/key-management
- Store as environment variable: `export NOVITA_API_KEY="sk_..."`
- Verify key is active and has sufficient credit at https://novita.ai/billing

### 2. Choose Your Integration Path
- **LLM API**: Call hosted models directly via OpenAI-compatible endpoints
- **Sandbox**: Run agent code in isolated environments
- **GPU**: Deploy models on dedicated or serverless GPUs

### 3. Make Your First Request
- For LLM: Send a chat completion request with model name, messages, and max_tokens
- For Sandbox: Create a sandbox, run commands, manage files
- For GPU: Create an instance, configure networking, deploy workload

### 4. Handle Responses and Errors
- Check HTTP status code (200 = success, 401 = auth, 403 = access denied, 429 = rate limit, 5xx = server error)
- Parse response body for `choices[0].message.content` (chat) or `choices[0].text` (completion)
- For errors, check error message and refer to error code guide

### 5. Optimize and Scale
- Use streaming for long outputs to prevent timeouts
- Use Batch API for non-urgent bulk requests
- Configure model access policies to restrict keys by purpose
- Monitor usage and set up auto-top-up for continuous operation

## Common Gotchas

- **Missing or malformed API key**: Ensure `Authorization: Bearer sk_<key>` format; check key exists in Key Management
- **Model access denied (403)**: Key is restricted to different models; ask team admin to adjust model access policy or use a different key
- **Identity verification required (403)**: Some models require account verification; complete verification in console first
- **Rate limit exceeded (429)**: Hitting TPM (tokens per minute) or RPM (requests per minute) limits; use exponential backoff or upgrade account
- **503/504 timeout errors**: Backend overload or long generation time; enable streaming mode, increase client timeout, or retry during off-peak
- **Batch API limitations**: Max 50,000 requests per batch, 100MB file size, 24-hour completion window (non-adjustable)
- **Sandbox state not persisting**: Ensure you're using v2 region (us-phx-1, default); v1 has limited persistence
- **GPU instance data loss**: Data on stopped instances deleted after 7 days; use Network Volume for persistent storage
- **Streaming mode gotcha**: When streaming, check `delta.content` not `message.content`; handle None values
- **Environment variable not loaded**: Verify shell session has `NOVITA_API_KEY` set; don't hardcode keys in code

## Verification Checklist

Before submitting work:

- [ ] API key is valid and stored securely (environment variable, not hardcoded)
- [ ] Request includes correct `Authorization: Bearer` header
- [ ] Model name matches available models (check with `/v1/models` endpoint)
- [ ] Account has sufficient credit (check balance endpoint)
- [ ] HTTP response status is 200 (or expected status for your use case)
- [ ] Response body contains expected fields (`choices[0].message.content` for chat, `choices[0].text` for completion)
- [ ] For Sandbox: sandbox is in Running state and commands execute without permission errors
- [ ] For GPU: instance is in Running state and networking is configured
- [ ] For Batch: input file is valid JSONL, all requests target same model, batch status is not FAILED or EXPIRED
- [ ] Error handling is in place for 401, 403, 429, 5xx responses
- [ ] Rate limits are respected (use exponential backoff for retries)

## Resources

- **Comprehensive navigation**: https://docs.novita.ai/llms.txt — page-by-page listing of all documentation
- **LLM API Guide**: https://docs.novita.ai/guides/llm-api — detailed model capabilities, parameters, code examples
- **API Reference**: https://docs.novita.ai/api-reference/api-reference-overview — all endpoints, authentication, error codes
- **Sandbox Documentation**: https://docs.novita.ai/guides/sandbox-overview — sandbox concepts, lifecycle, quick start
- **Error Codes**: https://docs.novita.ai/guides/error — troubleshooting 401, 403, 429, 503, 504, 500 errors
- **Batch API**: https://docs.novita.ai/guides/llm-batch-api — asynchronous bulk inference, file upload, status tracking
- **Model Access**: https://docs.novita.ai/guides/llm-model-access — restricting keys to specific models
- **API Key Management**: https://novita.ai/settings/key-management — create, store, configure keys
- **Billing**: https://novita.ai/billing — check credit, usage, payment settings

---

> For additional documentation and navigation, see: https://docs.novita.ai/llms.txt