Гузаштан ба мундариҷа

Барномасозон

Роҳнамои API

Ҳар як модели Milly Lab-ро аз коди худ истифода баред — бо ҳар забон, дар ҳар платформа, аз сервер ё браузер — тавассути API-и бо OpenAI мувофиқ, ки ҳисобро аз ҳисоби Milly Lab-и шумо мебарорад. Ин роҳнамо дархости аввал, танзими SDK, стриминг, нархҳои зинда, қоидаҳои ҳисоббарорӣ, маҳдудиятҳои калид, лимитҳо, кодҳои хато ва эндпоинти истифодаро дар бар мегирад.

Охирин навсозӣ:


URL-и асосӣ #

https://api.m-lab.app/v1

Ҳамаи эндпоинтҳои поён нисбат ба ин суроға оварда шудаанд. Ин дастур маълумотномаи API-и оммавӣ аст: Milly Lab схемаи OpenAPI-ро нашр намекунад.


Оғози зуд #

  1. Калид созед. Дар барномаи веб Танзимот → Амният → Калидҳои API-ро кушоед (тугмаи Идораи калидҳои API дар саҳифаи API низ ба ҳамон ҷо мебарад) ва Кушодани калидҳои API-ро пахш кунед. Саҳифаи калидҳои API дар Консоли пурра кушода мешавад; дар он ҷо Сохтани калид-ро пахш кунед. Дастрасӣ ба API ба тарофаи Max ва болотар дохил мешавад. Калиди хом (mk_…) як маротиба нишон дода мешавад; танҳо чор аломати охир нигоҳ дошта мешавад.
  2. OpenAI SDK-ро ба URL-и асосӣ равона кунед. Ҳар клиенте, ки протоколи OpenAI chat-completions-ро медонад, пас аз иваз кардани base URL кор мекунад.
  3. Моделро интихоб кунед аз GET /v1/models ва дархости аввалро фиристед.
curl https://api.m-lab.app/v1/chat/completions \
  -H "Authorization: Bearer $MILLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5",
       "messages": [{"role": "user", "content": "Се далел дар бораи Душанбе."}]}'

Ҷавоб — объекти стандартии chat.completion бо choices[0].message.content ва usage (токенҳое, ки барояшон маблағ гирифта шуд).


Танзими SDK #

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.m-lab.app/v1",
    api_key="mk_...",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Се далел дар бораи Душанбе."}],
)
print(r.choices[0].message.content, r.usage)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.m-lab.app/v1",
  apiKey: process.env.MILLY_API_KEY,
});

const r = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "Се далел дар бораи Душанбе." }],
});
console.log(r.choices[0].message.content, r.usage);

fetch-и оддӣ (ҳар муҳит)

const res = await fetch("https://api.m-lab.app/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: "Bearer " + MILLY_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "claude-sonnet-5",
    messages: [{ role: "user", content: "Се далел дар бораи Душанбе." }] }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

Майдонҳои дастгиришавандаи дархост: model, messages (нақшҳои system/developer, user, assistant; сатр ё қисмҳои text; дар моделҳое, ки capabilities.vision = true доранд, инчунин қисмҳои image_url — URL-и data: ё https: ба тасвири PNG, JPEG, GIF ё WebP то 5 МБ, на бештар аз 8 дар як дархост), stream, max_tokens / max_completion_tokens, reasoning_effort (low · medium · high). Майдонҳои сэмплинг (temperature, top_p, …) барои мувофиқат қабул мешаванд; сэмплингро роутери платформа ҳал мекунад. tools, tool_choice ва паёмҳои tool/function қабул мешаванд, вале ҳоло иҷро намешаванд — ниг. Чӣ дар пеш аст.


Стриминг #

stream: true-ро гузоред, то server-sent events гиред. Ҳар рӯйдод — chat.completion.chunk; чанки охирин finish_reason ва usage-ро дорад, сипас data: [DONE]. То даме ки модел фикр мекунад ва ҳанӯз наменависад, ҷараён ҳар чанд сония сатри шарҳ (: keepalive) мефиристад, то проксиҳо ва мизоҷон пайвастро набанданд; мизоҷони SSE, аз ҷумла SDK-ҳои OpenAI, чунин сатрҳоро нодида мегиранд.

Агар модел дар нимаи ҷавоб хато диҳад, ҷавоб ҳеҷ гоҳ пурра вонамуд карда намешавад: ҷараён рӯйдоди error мефиристад (рамзи upstream_interrupted; SDK-ҳои OpenAI дар он хато мебароранд) ва дар чанки охирин finish_reason: "error" аст; даъвати бе ҷараён 502 upstream_interrupted ҷавоб медиҳад: он чи модел то ин дам навишт — дар error.partial_content, usage-и гирифташуда — ҳамон ҷо, ва сарлавҳаи x-should-retry: false, то SDK даъватро худаш такрор накунад.

stream = client.chat.completions.create(model="claude-sonnet-5", stream=True,
    messages=[{"role": "user", "content": "Дар бораи кӯҳҳо ҳайку нависед."}])
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\n", chunk.usage)

Агар клиент дар миёни стрим қатъ шавад, генератсия дар платформа то охир идома меёбад ва токенҳои истеҳсолшуда пардохт мешаванд.


Моделҳо ва нархҳои зинда #

GET /v1/models оммавӣ аст (калид лозим нест) ва ҳар модели тавассути API дастрасро бо як нарх барои ҳар воҳид бармегардонад: арзиши даъват ҳангоми пардохт аз баланс.

{
  "id": "claude-sonnet-5",
  "display_name": "Claude Sonnet 5.5",
  "modality": "chat",
  "capabilities": { "vision": true, "tools": false, "streaming": true },
  "context_window": 1000000,
  "max_output_tokens": 64000,
  "pricing": {
    "unit": "per_1m_tokens",
    "input_per_1m_usd": 6.0,
    "output_per_1m_usd": 22.0,
    "cache_write_5m_per_1m_usd": 7.5,
    "cache_write_1h_per_1m_usd": 12.0,
    "cache_read_per_1m_usd": 0.3,
    "web_search_per_request_usd": 0.02
  }
}

Сатрҳои моделҳои Claude инчунин нархҳои токенҳои кэши промпт — cache_write_5m_per_1m_usd, cache_write_1h_per_1m_usd ва cache_read_per_1m_usd, барои 1 млн токен — ва web_search_per_request_usd, нархи як ҷустуҷӯи веб, доранд. Модели дорои нархи дуюм барои промптҳои дароз майдони long_context дорад; барои Claude Haiku 5.5 ин {"threshold_prompt_tokens": 100000, "input_per_1m_usd": 3.0, "output_per_1m_usd": 7.0, "cache_write_5m_per_1m_usd": 3.75, "cache_write_1h_per_1m_usd": 6.0, "cache_read_per_1m_usd": 0.3} аст. Сатрҳои моделҳои OpenAI cache_write_30m_per_1m_usd ва cache_read_per_1m_usd доранд. Сатри Grok низ web_search_per_request_usd дорад, вақте ки Grok ҷустуҷӯи веби худро анҷом медиҳад. Ҳар майдон чӣ гуна татбиқ мешавад — дар бахши «Қоидаҳои ҳисоббарорӣ» дар поён.

Моделҳои тасвир pricing.unit = "per_image" бо per_image_usd — нархи як тасвир бо сифати стандартӣ — ва per_quality_usd доранд — нархи як тасвир барои ҳар сифате, ки модел дастгирӣ мекунад (масалан, {"low": …, "standard": …, "high": …}): маҳз ҳамин қадар барои даъват бо он сифат аз баланс гирифта мешавад. Модели эмбеддинг бо modality: "embedding" оварда шудааст. Ҳангоми даъвати /v1/models бо калид ҳар сатр инчунин allowed_for_key-ро дорад — оё ин калид метавонад моделро даъват кунад — ва included_in_plan-ро — оё тарофаи ҳисоб ин моделро ҷудо мекунад (аввал лимит) ё ҳар даъват аз баланс пардохт мешавад; майдони болоии plan тарофаро ном мебарад. Бо баланси $0 модели дохилнашуда аз токени аввал 402 ҷавоб медиҳад.

Танҳо моделҳои номбаршуда даъватшавандаанд. Калиди аз кор баровардашуда бе ҷонишин (gpt-5.4-mini) 404 model_not_found ҷавоб медиҳад; тахаллуси кӯҳна, ки ба модели ҷорӣ ишора мекунад (claude-sonnet → claude-sonnet-5, claude-haiku-4-5 → claude-haiku-5-5, gpt-4o → gpt-5.4-nano), кор мекунад ва бо нархи нашршудаи модели ҷавобдиҳанда пардохт мешавад.

Ҷадвали зинда дар саҳифаи API-и барномаи веб аз ҳамин эндпоинт сохта мешавад.


Қоидаҳои ҳисоббарорӣ #

  1. Аввал тарофа. Агар модел ба тарофаи шумо дохил бошад, дархостро аввал лимити моҳонаи тарофа барои ин модел фаро мегирад.
  2. Сипас баланс. Ҳар чизе, ки лимит фаро намегирад, аз баланси пуркунӣ пардохт мешавад: токенҳо × нархи нишондодашудаи модел (input_per_1m_usd ва output_per_1m_usd; тасвирҳо: нархи per_quality_usd-и сифати дархостшуда барои ҳар тасвир (per_image_usd, агар quality нишон дода нашавад); эмбеддингҳо: нархи нишондодашуда барои 1 млн токени вуруд), ва ҳангоми татбиқ нархҳои промпти дароз, кэши промпт ва ҷустуҷӯи веб, ки дар поён оварда шудаанд. Ҳамаи нархҳо дар рӯйхати моделҳои API ва дар саҳифаи «Барои таҳиягарон» оварда шудаанд.
  3. Дар истифода арзиши ҳар дархост намоён аст. GET /v1/usage ҳар дархостро бо нархи нишондодашудааш ҳисоб мекунад, новобаста аз он ки онро лимити тарофа ё баланс пардохт кард; Танзимот → Пардохтҳо нишон медиҳад, ки чӣ қадар аз баланс гирифта шуд.
  4. Захира пеш аз харҷ. Дархосте, ки бо боқимондаи лимит ва баланс пӯшонида намешавад, бо 402 пеш аз муроҷиат ба провайдер рад мешавад; дар вақти генератсия платформа ҳолати бадтаринро нигоҳ медорад ва баъд ба истифодаи воқеӣ ҳисоб мекунад. Агар провайдери модел дар муҳит танзим нашуда бошад, ҷавоб 503 provider_unavailable аст — низ пеш аз ҳар гуна нигоҳдорӣ, бинобар ин ҳеҷ чиз гирифта намешавад. Провайдере, ки пеш аз натиҷа хато медиҳад — 502 бе пардохт; натиҷае, ки пеш аз хато стрим шудааст, пардохт мешавад.
  5. Маҳдудиятҳои калид (поён) лимити харҷ ва рӯйхати моделҳои иҷозатдодашударо бар болои қоидаҳои ҳисоб илова мекунанд.

Ҳар дархости API як сатри истифода бо нишони калид менависад; ин сатрҳо Танзимот → Ҳисоббарорӣ, нишондиҳандаи дар ин моҳ сарфшуда-и калид ва GET /v1/usage-ро таъмин мекунанд.

Промптҳои дароз, кэши промпт ва ҷустуҷӯи веб

Ҳар яке аз инҳо дар сатри модел дар GET /v1/models нархи нишондодашудаи худро дорад, ва usage-и ҷавоб шумораҳоеро дорад, ки ин нарх ба онҳо татбиқ мешавад:

  • Промптҳои дароз. Дархосте, ки промпташ — usage.prompt_tokens, ҳамаи токенҳои вуруд, аз ҷумла кэшшудаҳо — аз pricing.long_context.threshold_prompt_tokens зиёд аст, пурра бо нархҳои long_context пардохт мешавад. Claude Haiku 5.5: то 100 000 токени промпт — $2.20 барои 1 млн токени вуруд ва $3.00 барои 1 млн токени хуруҷ; аз он зиёд — $3.00 ва $7.00. Моделҳои OpenAI (аз 272 000 токени промпт зиёд) ва Grok (аз 200 000, дар рӯйхат — аз 199 999 зиёд) низ нархи дуюм доранд; нархи ҳар модел дар сатри худи он аст. Ҳар дархости даври абзорҳо аз рӯи промпти худ ҳисоб мешавад.
  • Кэши промпт (Claude). Claude ибтидоҳои такроршавандаи промптро дар кэш нигоҳ медорад. Аз токенҳои промпт онҳое, ки ба кэш навишта мешаванд (usage.prompt_tokens_details.cache_write_tokens, аз онҳо барои як соат — cache_write_1h_tokens), бо cache_write_5m_per_1m_usd (навиштан ба як соат — бо cache_write_1h_per_1m_usd) пардохт мешаванд, онҳое, ки аз кэш хонда мешаванд (usage.prompt_tokens_details.cached_tokens) — бо cache_read_per_1m_usd, боқимонда — бо input_per_1m_usd. Барои промпти дароз се нархи кэш аз long_context амал мекунанд.
  • Кэши промпт (OpenAI). Моделҳои OpenAI ибтидоҳои такроршавандаи промптро худкор дар кэш нигоҳ медоранд. Аз токенҳои промпт онҳое, ки ба кэш навишта мешаванд (usage.prompt_tokens_details.cache_write_tokens, 30 дақиқа нигоҳ дошта мешаванд), бо cache_write_30m_per_1m_usd пардохт мешаванд, онҳое, ки аз кэш хонда мешаванд (usage.prompt_tokens_details.cached_tokens) — бо cache_read_per_1m_usd, боқимонда — бо input_per_1m_usd. Барои промпти дароз ду нархи кэш аз long_context амал мекунанд.
  • Ҷустуҷӯи веб (Claude, Grok). Ҳар ҷустуҷӯи веб, ки модел барои ҷавоб анҷом медиҳад (usage.web_search_requests), web_search_per_request_usd-и сатри худро (Claude $0.02, Grok $0.01) илова мекунад.
  • Яклухткунӣ. Маблағи ҳар дархост то $0.000001 яклухт карда мешавад, бинобар ин ҷамъе, ки шумо аз нархҳои нишондодашуда ҳисоб мекунед, метавонад аз он ба чанд миллионяки доллар фарқ кунад.

Маҳдудиятҳои калид #

Ҳангоми сохтан ё баъдтар дар саҳифаи калидҳои API дар Консоли пурра (Танзимот → Амният → Калидҳои API → Кушодани калидҳои API) ё бо дархости PATCH /api/keys/{id} аз сессияи веб гузошта мешаванд:

МаҳдудиятРафтор
Лимити моҳонаи харҷ (USD, сентҳои пурра — 0.05, на 0.001; қимати дақиқтар бо 422 рад мешавад)Вақте ки харҷи калид аз аввали моҳ (ҳар дархост бо нархи нишондодашудааш, новобаста аз он ки онро лимити тарофа ё баланс пардохт кард) ба лимит мерасад, даъватҳои минбаъда 402 spend_cap_reached бармегардонанд. Дархосте, ки хатро мегузарад, ҳанӯз иҷро мешавад (арзиши он то анҷом номаълум аст), бинобар ин зиёдатӣ на бештар аз як дархост аст. Ҳар 1-уми моҳ (UTC) нав мешавад.
Моделҳои иҷозатдодашудаРӯйхати калидҳои каталог. Ҳар модели дигар 403 model_not_allowed бармегардонад. Холӣ = ҳамаи моделҳои API. Номҳои кӯҳна ба калиди ҷорӣ табдил дода мешаванд.

Ҳар дуро барои ҳар калиде, ки аз инфрасохтори худатон берун меравад, истифода баред.


Эмбеддингҳо #

POST /v1/embeddings — бо OpenAI мувофиқ. Модели text-embedding-3-small (1536 андоза). input — сатр ё рӯйхати то 256 сатр (ҳар кадом 12 000 аломат). Аз рӯи токенҳои вуруд пардохт мешавад; эмбеддингҳо ба ҳеҷ лимити тарофа дохил нестанд, бинобар ин ҳамеша аз баланс пардохт мешаванд. encoding_format — float (пешфарз) ё base64 (float32 little-endian — маҳз ҳаминро SDK-ҳои расмӣ пешфарз мепурсанд, бинобар ин client.embeddings.create(...) бе тағйир кор мекунад).

emb = client.embeddings.create(model="text-embedding-3-small", input=["Milly Lab", "public API"])
print(len(emb.data[0].embedding), emb.usage.prompt_tokens)

Тасвирҳо #

POST /v1/images/generations — дархост ва ҷавоби бо OpenAI мувофиқ. model — калиди модели тасвир аз /v1/models (gpt-image-2, gemini-nano-banana, fal-ai/flux-pro, fal-ai/stable-diffusion-xl), n 1–4, size 1024x1024 · 1536x1024 · 1024x1536 (ба наздиктарин таносуби модел табдил дода мешавад), quality low · standard · high (medium/hd қабул мешаванд). Даъват синхронӣ аст (то 180 с) ва url-ҳои ҷойгиршударо бармегардонад; usage.billed_usd маблағест, ки аз баланс гирифта шуд (0, агар тасвирҳоро лимити тарофа пӯшонда бошад).

img = client.images.generate(model="gpt-image-2", prompt="Харитаи обрангии Помир", size="1024x1024")
print(img.data[0].url)

Тасвирҳое, ки тавассути API сохта шудаанд, ба таърихи Light Studio илова намешаванд.


Эндпоинти истифода #

GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD[&key=<id>] дархостҳо, токенҳо ва харҷ бо нархҳои нишондодашуда-ро (ҳар дархост бо нархи нишондодашудааш, новобаста аз он ки онро лимити тарофа ё баланс пардохт кард) бармегардонад. Бо калиди маҳдуднашуда (бе рӯйхати моделҳо ва бе лимити харҷ) — барои ҳамаи калидҳои ҳисоб: як калиди ҳисоботӣ метавонад ҳамаро назорат кунад (scope: "account"). Калиди маҳдуд — бо рӯйхати моделҳои иҷозатдодашуда ё лимити харҷ, чунон ки барои калидҳое, ки дигарон метавонанд бубинанд (масалан, дар коди браузер), тавсия медиҳем, — танҳо харҷи худро мебинад (scope: "key"), ва key= бо калиди дигар 404 ҷавоб медиҳад. Давраи пешфарз — аз аввали моҳ; ҳадди аксар 92 рӯз. Чати барномаи веб ҳеҷ гоҳ дохил намешавад. tokens_in ҳамаи токенҳои вурудро, аз ҷумла кэшшудаҳо, ҳисоб мекунад — ҳамон тавре ки usage.prompt_tokens дар ҷавоб.

{
  "object": "usage",
  "from": "2026-09-01T00:00:00", "to": "2026-09-10T12:00:00",
  "totals": { "requests": 412, "tokens_in": 1830000, "tokens_out": 210000, "usd": 12.41 },
  "by_key": [{ "key_id": "…", "name": "prod", "hint": "a1b2", "requests": 400, "usd": 12.10 }],
  "by_model": [{ "model": "claude-sonnet-5", "requests": 300, "usd": 10.20 }]
}

Лимитҳо #

ЛимитҚимат
Дархостҳо барои як калид120 дар як дақиқа → 429 rate_limit_exceeded бо Retry-After (сония)
Калидҳои фаъол барои як ҳисоб5
Паёмҳо дар як дархост200
Аломатҳо дар як дархост400 000
Вурудҳои эмбеддинг дар як даъват256 × 12 000 аломат
Тасвирҳо дар як даъват4

Ҳар ҷавоби /v1 x-request-id дорад (req_…; ҳангоми муроҷиат ба дастгирӣ онро нишон диҳед — ин рақами худи даъват аст: бо даъват дар журнал навишта ва бо харҷи он нигоҳ дошта мешавад, ва id-и ҷавоби чат ҳамон аломатҳоро дорад) ва, пас аз аутентификатсияи калид, x-ratelimit-limit, x-ratelimit-remaining ва x-ratelimit-window (сония). 429 Retry-After илова мекунад — ҳамон қадар сония интизор шавед ва такрор кунед. 402-ро бе тағйир додани чизе такрор накунед (баланс пур кунед, лимитро боло баред, модели арзонтар интихоб кунед).


Кодҳои хато #

Ҳар хато дар шакли OpenAI аст: {"error": {"message": "…", "type": "…", "code": "…"}} — аз рӯи code шоха кунед.

HTTPcodeМаъно
400invalid_body · invalid_messages · invalid_inputДархости нодуруст, матни корбар нест, вуруди эмбеддинг бад
401missing_api_key · invalid_api_keyКалиди bearer нест ё бекор/номаълум аст
402insufficient_for_request · insufficient_balanceЛимит + баланс дархостро намепӯшонанд
402spend_cap_reachedЛимити моҳонаи ин калид расид
403api_access_requiredТарофаи ҳисоб дастрасӣ ба API надорад
403model_not_allowedМодел дар рӯйхати иҷозатдодашудаи калид нест
403account_disabledҲисоб боздошта шудааст
404model_not_foundМодели номаълум ё аз кор баровардашуда — танҳо сатрҳои /v1/models даъватшавандаанд
429rate_limit_exceededЛимити калид (120/дақ); Retry-After мегӯяд, чӣ қадар интизор шавед
502upstream_errorПровайдер пеш аз натиҷа хато дод — ҳеҷ чиз гирифта нашуд
502upstream_interruptedМодел дар нимаи ҷавоб хато дод — оғози ҷавоб дар error.partial_content аст ва гирифта шуд; x-should-retry: false
503provider_unavailableПровайдери модел (чат, эмбеддингҳо ё тасвир) дар ин муҳит танзим нашудааст — ҳеҷ чиз гирифта нашуд

Даъват аз браузер #

CORS дар /v1 барои ҳар манбаъ кушода аст (бе credentials), бинобар ин барномаҳои браузерӣ метавонанд бо Authorization: Bearer mk_… бевосита ба API муроҷиат кунанд. Калиде, ки дар коди браузер фиристода шудааст, ба ҳар меҳмон намоён аст. Барои чунин калидҳо: лимити сахти харҷ ва рӯйхати моделҳои иҷозатдодашуда гузоред, онҳоро мунтазам иваз кунед ё тавассути бэкенди худ, ки калид дар он махфӣ мемонад, прокси кунед.


Тавсияҳо #

  • Калидҳоро дар тағйирёбандаҳои муҳит ё менеҷери махфиятҳо нигоҳ доред, барои ҳар барнома ё муҳит як калид; калидҳои истифоданашавандаро бекор кунед.
  • Ба ҳар калид лимити харҷ гузоред; дар логҳо ба 402 spend_cap_reached огоҳӣ танзим кунед.
  • usage-ро аз ҳар ҷавоб (ё чанки охирини стрим) хонед ва бо GET /v1/usage муқоиса кунед.
  • Моделро мувофиқи вазифа интихоб кунед: нархҳо зиндаанд ва аксар вақт модели хурдтар кифоя аст.
  • Вақте ки андозаи ҷавобро медонед, max_tokens фиристед — ин захира ва ҳисобро маҳдуд мекунад.
  • Дар 429 Retry-After сония интизор шавед (таваққуфи экспоненсиалӣ илова бар он зарар надорад); 402 — сигнали танзимот аст, на хатои муваққатӣ.

Чӣ дар пеш аст #

  • Гузаронидани даъвати абзорҳо (tools / tool_choice қабул мешаванд, вале ҳоло иҷро намешаванд).
  • Генератсияи видео ва 3D тавассути /v1.
  • Рӯйхатҳои IP-и иҷозатдодашуда барои калид.