Барномасозон
Роҳнамои API
Ҳар як модели Milly Lab-ро аз коди худ истифода баред — бо ҳар забон, дар ҳар платформа, аз сервер ё браузер — тавассути API-и бо OpenAI мувофиқ, ки ҳисобро аз ҳисоби Milly Lab-и шумо мебарорад. Ин роҳнамо дархости аввал, танзими SDK, стриминг, нархҳои зинда, қоидаҳои ҳисоббарорӣ, маҳдудиятҳои калид, лимитҳо, кодҳои хато ва эндпоинти истифодаро дар бар мегирад.
URL-и асосӣ #
https://api.m-lab.app/v1
Ҳамаи эндпоинтҳои поён нисбат ба ин суроға оварда шудаанд. Ин дастур маълумотномаи API-и оммавӣ аст: Milly Lab схемаи OpenAPI-ро нашр намекунад.
Оғози зуд #
- Калид созед. Дар барномаи веб Танзимот → Амният → Калидҳои API-ро кушоед (тугмаи Идораи калидҳои API дар саҳифаи API низ ба ҳамон ҷо мебарад) ва Кушодани калидҳои API-ро пахш кунед. Саҳифаи калидҳои API дар Консоли пурра кушода мешавад; дар он ҷо Сохтани калид-ро пахш кунед. Дастрасӣ ба API ба тарофаи Max ва болотар дохил мешавад. Калиди хом (
mk_…) як маротиба нишон дода мешавад; танҳо чор аломати охир нигоҳ дошта мешавад. - OpenAI SDK-ро ба URL-и асосӣ равона кунед. Ҳар клиенте, ки протоколи OpenAI chat-completions-ро медонад, пас аз иваз кардани base URL кор мекунад.
- Моделро интихоб кунед аз
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-и барномаи веб аз ҳамин эндпоинт сохта мешавад.
Қоидаҳои ҳисоббарорӣ #
- Аввал тарофа. Агар модел ба тарофаи шумо дохил бошад, дархостро аввал лимити моҳонаи тарофа барои ин модел фаро мегирад.
- Сипас баланс. Ҳар чизе, ки лимит фаро намегирад, аз баланси пуркунӣ пардохт мешавад: токенҳо × нархи нишондодашудаи модел (
input_per_1m_usdваoutput_per_1m_usd; тасвирҳо: нархиper_quality_usd-и сифати дархостшуда барои ҳар тасвир (per_image_usd, агарqualityнишон дода нашавад); эмбеддингҳо: нархи нишондодашуда барои 1 млн токени вуруд), ва ҳангоми татбиқ нархҳои промпти дароз, кэши промпт ва ҷустуҷӯи веб, ки дар поён оварда шудаанд. Ҳамаи нархҳо дар рӯйхати моделҳои API ва дар саҳифаи «Барои таҳиягарон» оварда шудаанд. - Дар истифода арзиши ҳар дархост намоён аст.
GET /v1/usageҳар дархостро бо нархи нишондодашудааш ҳисоб мекунад, новобаста аз он ки онро лимити тарофа ё баланс пардохт кард; Танзимот → Пардохтҳо нишон медиҳад, ки чӣ қадар аз баланс гирифта шуд. - Захира пеш аз харҷ. Дархосте, ки бо боқимондаи лимит ва баланс пӯшонида намешавад, бо 402 пеш аз муроҷиат ба провайдер рад мешавад; дар вақти генератсия платформа ҳолати бадтаринро нигоҳ медорад ва баъд ба истифодаи воқеӣ ҳисоб мекунад. Агар провайдери модел дар муҳит танзим нашуда бошад, ҷавоб 503
provider_unavailableаст — низ пеш аз ҳар гуна нигоҳдорӣ, бинобар ин ҳеҷ чиз гирифта намешавад. Провайдере, ки пеш аз натиҷа хато медиҳад — 502 бе пардохт; натиҷае, ки пеш аз хато стрим шудааст, пардохт мешавад. - Маҳдудиятҳои калид (поён) лимити харҷ ва рӯйхати моделҳои иҷозатдодашударо бар болои қоидаҳои ҳисоб илова мекунанд.
Ҳар дархости 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 шоха кунед.
| HTTP | code | Маъно |
|---|---|---|
| 400 | invalid_body · invalid_messages · invalid_input | Дархости нодуруст, матни корбар нест, вуруди эмбеддинг бад |
| 401 | missing_api_key · invalid_api_key | Калиди bearer нест ё бекор/номаълум аст |
| 402 | insufficient_for_request · insufficient_balance | Лимит + баланс дархостро намепӯшонанд |
| 402 | spend_cap_reached | Лимити моҳонаи ин калид расид |
| 403 | api_access_required | Тарофаи ҳисоб дастрасӣ ба API надорад |
| 403 | model_not_allowed | Модел дар рӯйхати иҷозатдодашудаи калид нест |
| 403 | account_disabled | Ҳисоб боздошта шудааст |
| 404 | model_not_found | Модели номаълум ё аз кор баровардашуда — танҳо сатрҳои /v1/models даъватшавандаанд |
| 429 | rate_limit_exceeded | Лимити калид (120/дақ); Retry-After мегӯяд, чӣ қадар интизор шавед |
| 502 | upstream_error | Провайдер пеш аз натиҷа хато дод — ҳеҷ чиз гирифта нашуд |
| 502 | upstream_interrupted | Модел дар нимаи ҷавоб хато дод — оғози ҷавоб дар error.partial_content аст ва гирифта шуд; x-should-retry: false |
| 503 | provider_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-и иҷозатдодашуда барои калид.