Nebius Token Factory API Skill

Install: npx skills add diskd-ai/nebius-api | skills.sh

Integration skill for building AI-powered applications with Nebius Token Factory (tokenfactory.nebius.com) and its OpenAI-compatible API.

---

Scope & Purpose

This skill provides guidance and patterns for working with Nebius Token Factory, covering:

• OpenAI-compatible inference: chat/completions/embeddings/images
• Streaming (SSE) and tool/function calling
• JSON mode / structured outputs
• Model discovery (GET /v1/models, verbose=true)
• Files and batch processing
• Fine-tuning jobs (OpenAI-style)
• Token Factory extensions: datasets multipart uploads and operations (checkpoints/results)
• Custom model management (/v0/models)

---

When to Use This Skill

Triggers:

• Mentions of Nebius Token Factory, tokenfactory.nebius.com, or ai_project_id
• Implementing a Nebius provider adapter/client in TypeScript/JavaScript/Python
• Configuring OpenAI-compatible tooling (OpenAI SDK, LangChain, LiteLLM, etc.) to target Nebius
• Migrating from Nebius AI Studio keys to Token Factory keys/base URL

Use cases:

• Add chat completions via OpenAI SDK with baseURL=https://api.tokenfactory.nebius.com/v1/
• Implement streaming responses and tool calls
• List/choose models dynamically from /v1/models
• Upload files and run batch jobs
• Run fine-tuning jobs and inspect status
• Upload datasets and run/stop operations; inspect checkpoints and results

---

Quick Reference

Installation

# Python
pip install openai

# TypeScript/JavaScript
npm install openai

Environment

export NEBIUS_API_KEY=<your-api-key>
# Optional: scope requests to a specific project
export NEBIUS_AI_PROJECT_ID=<your-project-id>

Basic Usage

Python (OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    api_key="<NEBIUS_API_KEY>",
    base_url="https://api.tokenfactory.nebius.com/v1/",
)

response = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Hello"}],
)

TypeScript (OpenAI SDK):

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEBIUS_API_KEY,
  baseURL: 'https://api.tokenfactory.nebius.com/v1/',
});

const response = await client.chat.completions.create({
  model: 'your-model-id',
  messages: [{ role: 'user', content: 'Hello' }],
});

---

Model Selection Guide

Availability changes over time; always fetch the canonical list from GET /v1/models (use verbose=true when needed).

Use Case	How to Choose	Notes
Fast + cheap	pick a small instruct/chat model	best for simple tasks
Balanced	pick a mid/large instruct model	quality/cost balance
Highest quality	pick the strongest instruct model	highest latency/cost
Reasoning	pick a reasoning-tuned model	may be slower
Code	pick a coder model	best for coding tasks
Embeddings	pick an embedding model	for RAG/semantic search
Images	pick an image model	for image generation

---

Skill Structure

nebius-api/
  SKILL.md          # Full reference and patterns
  README.md         # This file (overview)
  references/       # Supporting documentation
    basics.md
    endpoints.md
    datasets-and-operations.md
  scripts/
    nebius-smoke-test.mjs

---

Key Patterns

Project scoping (ai_project_id)

Some workflows require explicit project scoping via ai_project_id. Use request-level query params (SDK) or raw HTTP.

Streaming responses (SSE)

Treat streaming as Server-Sent Events (SSE): parse data: frames and stop on [DONE].

JSON mode / structured outputs

Use OpenAI-style response_format (when supported by the chosen model) to force machine-readable output.

---

Smoke Test

Run a minimal check against /models and /chat/completions:

NEBIUS_API_KEY=... node scripts/nebius-smoke-test.mjs

---

Migration note

Nebius AI Studio API keys remain valid only until January 31, 2026. Token Factory uses different keys and base URL.

---

Resources

• Full skill reference: SKILL.md
• Auth/base URL + migration notes: references/basics.md
• Endpoint map: references/endpoints.md
• Datasets and operations: references/datasets-and-operations.md
• Official docs: https://docs.tokenfactory.nebius.com/
• Cookbook: https://github.com/nebius/token-factory-cookbook

---

License

MIT