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

Роҳнамои API

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

Санаи охирин баррасӣ: 2026-09-10

#URL-и асосӣ

https://aria-web-production-a38d.up.railway.app/v1

Ҳамаи эндпоинтҳои поён нисбат ба ин суроға оварда шудаанд. Маълумотномаи интерактивии OpenAPI (/docs) дар муҳитҳои ғайри-продакшн дастрас аст; ҳамон амалиётҳо дар ин ҷо тасвир шудаанд.

#Оғози зуд

1. Калид созед. Дар барномаи веб: Танзимот → Амният → Калидҳои API → Сохтани калид (тугмаи Идораи калидҳои API дар саҳифаи API онро бевосита мекушояд). Дастрасӣ ба API ба тарофаи Max ва болотар дохил мешавад. Калиди хом (mk_…) як маротиба нишон дода мешавад; танҳо чор аломати охир нигоҳ дошта мешавад.
2. OpenAI SDK-ро ба URL-и асосӣ равона кунед. Ҳар клиенте, ки протоколи OpenAI chat-completions-ро медонад, пас аз иваз кардани base URL кор мекунад.
3. Моделро интихоб кунед аз GET /v1/models ва дархости аввалро фиристед.

curl https://aria-web-production-a38d.up.railway.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://aria-web-production-a38d.up.railway.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://aria-web-production-a38d.up.railway.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://aria-web-production-a38d.up.railway.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), 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].

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",
  "modality": "chat",
  "capabilities": { "vision": true, "tools": true, "streaming": true },
  "context_window": 1000000,
  "max_output_tokens": 64000,
  "pricing": {
    "unit": "per_1m_tokens",
    "input_per_1m_usd": 2.0,
    "output_per_1m_usd": 10.0,
    "platform_fee_per_1m_usd": 1.0,
    "effective_input_per_1m_usd": 3.0,
    "effective_output_per_1m_usd": 11.0
  }
}

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

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

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

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

1. Арзиши дархост = нархи провайдер × токенҳо + ҳаққи платформа $1 барои 1 млн токени вуруд ва $1 барои 1 млн токени баромад (тасвирҳо: $0.01 барои як тасвир; эмбеддингҳо: нархи провайдер + $1 барои 1 млн токени вуруд).
2. Аввал тарофа. Лимити моҳонаи тарофаи шумо барои ин модел аввал сарф мешавад.
3. Сипас баланс бо 2×. Ҳар чизе зиёда аз лимит аз баланси пуркунӣ бо ду баробар арзиш гирифта мешавад (ҳамон изофаи барномаи веб).
4. Захира пеш аз харҷ. Дархосте, ки бо боқимондаи лимит ва баланс пӯшонида намешавад, бо 402 пеш аз муроҷиат ба провайдер рад мешавад; дар вақти генератсия платформа ҳолати бадтаринро нигоҳ медорад ва баъд ба истифодаи воқеӣ ҳисоб мекунад. Агар провайдери модел дар муҳит танзим нашуда бошад, ҷавоб 503 provider_unavailable аст — низ пеш аз ҳар гуна нигоҳдорӣ, бинобар ин ҳеҷ чиз гирифта намешавад. Провайдере, ки пеш аз натиҷа хато медиҳад — 502 бе пардохт; натиҷае, ки пеш аз хато стрим шудааст, пардохт мешавад.
5. Маҳдудиятҳои калид (поён) лимити харҷ ва рӯйхати моделҳои иҷозатдодашударо бар болои қоидаҳои ҳисоб илова мекунанд.

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

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

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

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

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

POST /v1/embeddings — бо OpenAI мувофиқ. Модели text-embedding-3-small (1536 андоза). input — сатр ё рӯйхати то 256 сатр (ҳар кадом 12 000 аломат). Аз рӯи токенҳои вуруд пардохт мешавад; эмбеддингҳо ба ҳеҷ лимити тарофа дохил нестанд, бинобар ин аз баланс бо 2× пардохт мешаванд. 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 маблағи гирифташуда аст.

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>] дархостҳо, токенҳо ва долларҳои гирифташуда (тарофа + баланс, бо ҳаққи платформа)-ро барои ҳамаи калидҳои ҳисоб бармегардонад — як калиди ҳисоботӣ метавонад ҳамаро назорат кунад. Давраи пешфарз — аз аввали моҳ; ҳадди аксар 92 рӯз. Чати барномаи веб ҳеҷ гоҳ дохил намешавад.

{
  "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 }]
}

#Лимитҳо

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

#Кодҳои хато

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

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

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-и иҷозатдодашуда барои калид.