Nebius AI Studio documentation

Examples of using the Nebius AI Studio API

For the following examples to work, save your API key to the NEBIUS_API_KEY environment variable.

Text generation: v1/chat/completions

Request

Here is a sample JSON request body that includes all supported fields:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

completion = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-70B-Instruct",
    messages=[
        {
          "role": "system",
          "content": "You are a chemistry expert. Add jokes about cats to your responses from time to time."
        },
        {
          "role": "user",
          "content": "Hello!"
        },
        {
          "role": "assistant",
          "content": "Hello! How can I assist you with chemistry today? And did you hear about the cat who became a chemist? She had nine lives, but she only needed one formula!"
        }
    ],
    max_tokens=100,
    temperature=1,
    top_p=1,
    top_k=50,
    n=1,
    stream=false,
    stream_options=null,
    stop=null,
    presence_penalty=0,
    frequency_penalty=0,
    logit_bias=null,
    logprobs=false,
    top_logprobs=null,
    user=null,
    extra_body={
        "guided_json": {"type": "object", "properties": {...}}
    },
    response_format={
        "type": "json_object"
    }
)

print(completion.to_json())

curl 'https://api.studio.nebius.com/v1/chat/completions' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  --data-binary '{
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "messages": [
      {
        "role": "system",
        "content": "You are a chemistry expert. Add jokes about cats to your responses from time to time."
      },
      {
        "role": "user",
        "content": "Hello!"
      },
      {
        "role": "assistant",
        "content": "Hello! How can I assist you with chemistry today? And did you hear about the cat who became a chemist? She had nine lives, but she only needed one formula!"
      }
    ],
    "max_tokens": 100,
    "temperature": 1,
    "top_p": 1,
    "top_k": 50,
    "n": 1,
    "stream": false,
    "stream_options": null,
    "stop": null,
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "logit_bias": null,
    "logprobs": false,
    "top_logprobs": null,
    "user": null,
    "guided_json": {"type": "object", "properties": {...}}
    "response_format": {"type": "json_object"}
  }
  '

const OpenAI = require("openai");

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

client.chat.completions.create({
  "max_tokens": 100,
  "temperature": 1,
  "top_p": 1,
  "top_k": 50,
  "n": 1,
  "stream": false,
  "stream_options": null,
  "stop": null,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "logit_bias": null,
  "logprobs": false,
  "top_logprobs": null,
  "user": null,
  "extra_body": {
    "guided_json": {"type": "object", "properties": {...},}
  },
  "response_format": {
    "type": "json_object"
  },
  "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
  "messages": [
    {
      "role": "system",
      "content": "You are a chemistry expert. Add jokes about cats to your responses from time to time."
    },
    {
      "role": "user",
      "content": "Hello!"
    },
    {
      "role": "assistant",
      "content": "Hello! How can I assist you with chemistry today? And did you hear about the cat who became a chemist? She had nine lives, but she only needed one formula!"
    }
  ]
})
.then((completion) => console.log(completion));

Response

{
  "id": "cmpl-*****",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "Hello! It's nice to meet you. Is there something I can help you with, or would you like to chat?",
        "role": "assistant",
        "function_call": null,
        "tool_calls": []
      },
      "stop_reason": null
    }
  ],
  "created": 1721397089,
  "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
  "object": "chat.completion",
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 26,
    "prompt_tokens": 12,
    "total_tokens": 38
  }
}

For detailed field descriptions, see the API reference.

Vision capabilities: v1/chat/completions

You can pass images in the following ways:

  • A URL to the image.
  • A base64 encoded image directly in the request.
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

response = client.chat.completions.create(
    model="Qwen/Qwen2-VL-72B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What’s in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
                    },
                },
            ],
        }
    ],
    max_tokens=300,
)

print(response.choices[0])

curl 'https://api.studio.nebius.com/v1/chat/completions' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  --data-binary '{
    "model": "Qwen/Qwen2-VL-72B-Instruct",
    "messages": [
      {
        "role": "user",
        "content": [
        {
          "type": "text",
          "text": "What’s in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
          }
        }
      ]
      }
    ],
    "max_tokens": 100
  }
  '

const OpenAI = require("openai");

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

client.chat.completions.create({
  "max_tokens": 100,
  "temperature": 1,
  "top_p": 1,
  "top_k": 50,
  "n": 1,
  "stream": false,
  "stream_options": null,
  "stop": null,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "logit_bias": null,
  "logprobs": false,
  "top_logprobs": null,
  "user": null,
  "extra_body": {
    "guided_json": {"type": "object", "properties": {...},}
  },
  "response_format": {
    "type": "json_object"
  },
  "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
  "messages": [
    {
      "role": "user",
      "content": [
        { type: "text", text: "What’s in this image?" },
        {
          type: "image_url",
          image_url: {
            "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
          },
        },
      ]
    }
  ]
})
.then((completion) => console.log(completion));

For detailed field descriptions, see the API reference.

Text generation for code autocomplete: v1/completions

Request

Here is a sample JSON request body that contains all supported fields:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

for chunk in client.completions.create(
        model="meta-llama/Meta-Llama-3.1-70B-Instruct",
        prompt="Say my name",
        max_tokens=7,
        temperature=0,
        stream=True
):
    print(chunk.choices[0].text)

curl 'https://api.studio.nebius.com/v1/completions' \
  -H "Content-Type: application/json" \
  -H "Authorization: $NEBIUS_API_KEY" \
  -d '{
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct"
    "prompt": "Say my name",
    "max_tokens": 7,
    "temperature": 0,
    "stream": true
  }'

import OpenAI from "openai";

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

async function main() {
  const stream = await openai.completions.create({
    model: "meta-llama/Meta-Llama-3.1-70B-Instruct",
    prompt: "Say my name",
    stream: true,
  });

  for await (const chunk of stream) {
    console.log(chunk.choices[0].text);
  }
}

main();

Response

{
  "id": "cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe",
  "object": "text_completion",
  "created": 1690759111,
  "choices": [
    {
      "text": "Heisenberg",
      "index": 0,
      "logprobs": null,
      "finish_reason": null
    }
  ],
  "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
  "system_fingerprint": "fp_44709d6aaa"
}

For detailed field descriptions, see the API reference.

List of models: v1/models

Request

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

client.models.list() 

curl https://api.studio.nebius.com/v1/models \
  -H "Authorization: Bearer $NEBIUS_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": 'meta-llama/Meta-Llama-3.1-8B-Instruct',
      "object": "model",
      "created": 1724480826,
      "owned_by": 'system'
    },
    {
      "id": 'meta-llama/Meta-Llama-3.1-70B-Instruct',
      "object": "model",
      "created": 1724480826,
      "owned_by": 'system'
    },
  ],
  "object": "list"
}

For detailed field descriptions, see the API reference.

Image generation: v1/images/generations

Request

from openai import OpenAI
client = OpenAI()

client.images.generate(
    model="stability-ai/sdxl",
    prompt="An elephant in a desert",
    response_format="b64_json",
    extra_body={
        "response_extension": "webp",
        "width": 512,
        "height": 512,
        "num_inference_steps": 30,
        "seed": -1,
        "negative_prompt": "Giraffes, night sky"
    }
)

curl https://api.studio.nebius.com/v1/images/generations \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stability-ai/sdxl",
    "prompt": "An elephant in a desert",
    "response_format": "b64_json",
    "response_extension": "webp",
    "width": 512,
    "height": 512,
    "num_inference_steps": 30,
    "seed": -1,
    "negative_prompt": "Giraffes, night sky"
  }'

import OpenAI from "openai";

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

client.images.generate({
  model: "stability-ai/sdxl",
  prompt: "An elephant in a desert",
  response_format: "b64_json",
  extra_body: {
    response_extension: "webp",
    width: 512,
    height: 512,
    num_inference_steps: 30,
    seed: -1,
    negative_prompt: "Giraffes, night sky",
  },
}).then((completion) => {
  console.log(completion.data);
});

Response

{
  "data": [
    {
      "b64_json": "UklGRg66Ag..."
    }
  ],
  "id": "text2img-0941c39c-..."
}

{
  "data": [
    {
      "url": "https://pictures-storage-dev.storage.eu-north1.nebius.cloud/text2img-0941c39c-....webp"
    }
  ],
  "id": "text2img-0941c39c-..."
}

Note

Save the image once you receive the link. Nebius AI Studio does not store the image by the sent link permanently.

For detailed field descriptions, see the API reference.

Create embeddings: v1/embeddings

Request

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

client.embeddings.create(
    model="BAAI/bge-en-icl",
    input="Wake up, Neo...",
    encoding_format="float"
)

curl https://api.studio.nebius.com/v1/embeddings \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input": "Wake up, Neo...",
      "model": "BAAI/bge-en-icl",
      "encoding_format": "float"
  }'

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... (1536 floats total for BAAI/bge-en-icl)
        -0.0028842222,
      ],
      "index": 0
    }
  ],
  "model": "BAAI/bge-en-icl",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

For detailed field descriptions, see the API reference.

Files: v1/files

Upload a file: POST v1/files

Request
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

batch_requests = client.files.create(
    file=open("batch-requests.jsonl", "rb"),
    purpose="batch"
)

curl https://api.studio.nebius.com/v1/files \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -F purpose="batch" \
  -F file="@batch-requests.jsonl"
Response
{
  "id": "file-123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1730723658,
  "filename": "batch-requests.jsonl",
  "purpose": "batch"
}

Get file info: GET v1/files/{file_id}

Request
client.files.retrieve("file-123")

curl https://api.studio.nebius.com/v1/files/file-123 \
  -H "Authorization: Bearer $NEBIUS_API_KEY"
Response
{
  "id": "file-123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1730723658,
  "filename": "batch-requests.jsonl",
  "purpose": "batch"
}

Get file content: GET v1/files/{file_id}/content

Request
batch_result = client.files.content("file-123")
print(batch_result.text)

curl https://api.studio.nebius.com/v1/files/file-123/content \
  -H "Authorization: Bearer $NEBIUS_API_KEY" > batch_result.jsonl

List files: GET v1/files

Request
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

client.files.list()

curl https://api.studio.nebius.com/v1/files \
  -H "Authorization: Bearer $NEBIUS_API_KEY"
Response
{
  "data": [
    {
      "id": "file-123",
      "object": "file",
      "bytes": 120000,
      "created_at": 1730723658,
      "filename": "batch-requests.jsonl",
      "purpose": "batch"
    },
    {
      "id": "file-789",
      "object": "file",
      "bytes": 120,
      "created_at": 1731493853,
      "filename": "health-records-batch.jsonl",
      "purpose": "batch"
    }
  ],
  "object": "list"
}

Delete a file: DELETE v1/files/{file_id}

Request
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

client.files.delete("batch_123")

curl https://api.studio.nebius.com/v1/files/batch_123 \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -X DELETE
Response
{
  "id": "batch_123",
  "object": "file",
  "deleted": true
}

For detailed field descriptions, see the API reference.

Batches: v1/batches

Create a batch: POST v1/batches

Request
client.batches.create(
    input_file_id=batch_requests.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "description": "Asynchronous job"
    }
)

curl https://api.studio.nebius.com/v1/batches \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'
Response
{
  "id": "batch_123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1730723835,
  "in_progress_at": null,
  "expires_at": 1730810235,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123",
    "batch_description": "Asynchronous job"
  }
}

Get batch info: GET v1/batches/{batch_id}

Request
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

client.batches.retrieve("batch_123")

curl https://api.studio.nebius.com/v1/batches/batch_123 \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -F purpose="batch" \
  -H "Content-Type: application/json" \
Response
{
  "id": "batch_123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1730723835,
  "in_progress_at": null,
  "expires_at": 1730810235,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123",
    "batch_description": "Asynchronous job"
  }
}

List batches: GET v1/batches

Request
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.studio.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY"),
)

client.batches.list()

curl https://api.studio.nebius.com/v1/batches?limit=5 \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -H "Content-Type: application/json"
Response
{
  "object": "list",
  "data": [
    {
      "id": "batch_123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-re45SV",
      "error_file_id": "file-TrOWL1",
      "created_at": 1730723835,
      "in_progress_at": 1730723839,
      "expires_at": 1730810235,
      "finalizing_at": 1730797684,
      "completed_at": 1730797702,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 120,
        "completed": 117,
        "failed": 3
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Asyncronous job"
      }
    },
    { ... },
  ],
  "first_id": "batch_123",
  "last_id": "batch_987",
  "has_more": true
}

Cancel a batch: POST v1/batches/{batch_id}/cancel

Request
client.batches.cancel("batch_123")

curl https://api.studio.nebius.com/v1/batches/batch_123/cancel \
  -H "Authorization: Bearer $NEBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST
Response
{
  "id": "batch_123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1730723835,
  "in_progress_at": null,
  "expires_at": 1730810235,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1730735840,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 20,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123",
    "batch_description": "Asynchronous job"
  }
}

To learn more about batch inference, see Batch inference. For detailed field descriptions, see the API reference.

Previous
API reference
Next
Terms of service
In this article: