API
API: connect your software to AI-CLOUD
If you already have an application with us, the API is how your other programs work with it: the warehouse system, the accounting package or your website. It also gives you the AI models, paid for from your credits. We wrote the page so that you can pass it straight to whoever maintains the other program.
Last revised: 2 September 2026
What it does
There are two entrances and both use the same key. When you issue the key you decide whether it opens one of them or both.
- AI models. Your program sends a question and gets an answer from a language model. The cost comes out of your credits with us, so you need neither a contract with the model vendor nor their key.
- A bridge to your application. Another system calls the application you built with us through our address. Calls are rate-limited and logged, and each one carries a signature that shows it really came from us.
Getting started
It takes about two minutes. Keys can be issued by the owner or an administrator of the account. Members and viewers cannot issue them, because a key spends the whole account’s credits and works without signing in.
- Sign in to the portal and open API from the menu.
- Press “Issue a key”, give it a name, pick the project and choose what it may be used for.
- The key appears on screen once, so save it straight away. We do not keep it and cannot show it to you again. If you lose it, revoke it and issue a new one.
- Try it with the first command below.
The address and the key
Everything goes through one address. The key is sent in the
Authorization header, the same as in most APIs you have probably
used before.
curl https://ai-cloud.ro/api/v1/me \
-H "Authorization: Bearer YOUR_KEY"
{
"key": {
"name": "Warehouse system",
"masked": "ak_live_…f3c9",
"scopes": ["ai"],
"project": "43baa9f08a20"
},
"balanceCredits": 4820,
"limits": { "perMinute": 60, "perDay": 5000 }
}
Which models are offered
It is best for your program to ask for the list itself, so that an outdated copy does not sit in its code. The prices in the answer are the ones you pay, which is exactly what you will be charged.
- Prices are in micro-credits per 1000 tokens. 1000 micro-credits = 1 credit.
- A token is about three or four characters of text. An ordinary question together with its answer comes to a few hundred tokens.
- We offer the Anthropic models, since the entrance uses their request format. If you need a different vendor, write to us.
curl https://ai-cloud.ro/api/v1/models \
-H "Authorization: Bearer YOUR_KEY"
{
"models": [
{
"model": "claude-haiku-4-5",
"contextWindow": 200000,
"inputPricePer1kMicro": 180,
"outputPricePer1kMicro": 900
}
]
}
One AI call
The request body has the same shape as Anthropic’s. If your program already works with their API, you change the address and the key and nothing else. You get the answer whole, exactly as we received it.
max_tokenssets how long the answer can be at most. We accept no more than 4096, so you know in advance what the most expensive call could cost.- Streaming (
"stream": true) is not supported. We refuse such a request with a clear message and never quietly alter it. - A call gets 25 seconds. If the model has not answered in that time, you get an error and stop waiting.
curl https://ai-cloud.ro/api/v1/ai/messages \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-haiku-4-5",
"max_tokens": 300,
"messages": [
{ "role": "user", "content": "Summarise this complaint in one sentence: ..." }
]
}'
X-AICLOUD-Cost-Micro: 9
X-AICLOUD-Charged: 1
What it costs
You pay what the call cost, plus a 20% margin. We work out the charge after the
answer, from the real token counts, and hold nothing back in advance. Before we
send the request, though, we check that your balance covers the most expensive
possible result (your text plus the full max_tokens). If it does
not, we refuse the request at once, so you are never left owing anything.
- What was taken is visible immediately in the response headers and on the “API” screen in the portal. Header names are case-insensitive, and most clients hand them back in lower case.
- When your credits do not cover the most expensive possible result, the request is refused before it goes out. Nothing is spent, no debt builds up, and the answer tells you how many credits are needed and how many you have.
- If you use prompt caching, the cached tokens are billed as well: writing to the cache costs 1.25× the input price and reading from it 0.1×. You do save, though not all of it.
- Each key can have a monthly cap in credits. Once it hits the cap only that key stops, and the others carry on.
- The bridge to your application costs no credits, because the project’s hosting, which you already pay for, covers it.
input tokens 16 × 150 micro-credits / 1000 = 2.40
output tokens 6 × 750 micro-credits / 1000 = 4.50
────
cost 6.90 → 7 micro-credits
with the 20% margin 9 micro-credits
(= 0.009 credits)
The bridge to your application
Another system calls your application through our address. The advantage is that we sit in the middle. You revoke the key with one button, calls are rate-limited, and the log shows who called and when.
- The address is declared in the portal, on the API screen, per project.
- We accept only
https://and only domain names, with no numeric addresses. - Whatever follows the project id is added unchanged to your address, query string and all.
curl https://ai-cloud.ro/api/v1/p/43baa9f08a20/orders \
-H "Authorization: Bearer A_BRIDGE_KEY"
↓ reaches your address
https://your-application.com/orders
Why we ask you to prove the address is yours
A declared address does not start working straight away. First you show that the domain belongs to you. Otherwise anyone could enter someone else’s site and hammer it in our name, from our address. You only do this once, and it takes a minute.
- The portal shows you a string of the form
aicloud-verify-…. - Make
https://your-address/.well-known/aicloud-gateway.txtreturn that string as plain text. - Press “Prove ownership” and you are finished.
- If you change the address, the proof is cleared and you do it again. Proof given for one domain does not carry over to another.
Make /.well-known/aicloud-gateway.txt return this text
as plain text: aicloud-verify-xxxxxxxx
How your application knows it is us
Every bridge call arrives signed. Your application works out the signature too, using the shared secret from the portal, and compares it with the one it received. That way, someone who guesses your address still cannot pass for us.
- We sign the time, the method, the path and the hash of the body, so more than the body alone. A signature therefore cannot be reused for a different path.
- The path is exactly the one your server receives, query string included and encoded as it arrived. In Node that is
req.urluntouched: do not decode it and do not strip the query before computing the signature. - If your address has a prefix (
https://your-site.com/api), that prefix is part of the signed path too, just as it is part of the request you receive. - You can see the secret in the portal at any time and replace it with one button. The old one stops working from that moment.
X-AICLOUD-Signature: t=1788332240,v1=5c4afbda789bcceb…
X-AICLOUD-Timestamp: 1788332240
X-AICLOUD-Project: 43baa9f08a20
X-AICLOUD-Caller-Ip: 78.47.88.53
User-Agent: AICLOUD-Gateway/1
import { createHmac, createHash, timingSafeEqual } from 'node:crypto';
function verify(req, body, secret) {
const [t, v1] = req.headers['x-aicloud-signature']
.split(',').map(part => part.split('=')[1]);
// An old signature is not accepted: that is what the signed time is for.
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const hash = createHash('sha256').update(body).digest('hex');
const payload = `${t}.${req.method}\n${req.url}\n${hash}`;
const ours = createHmac('sha256', secret).update(payload).digest('hex');
return ours.length === v1.length
&& timingSafeEqual(Buffer.from(ours), Buffer.from(v1));
}
What does NOT reach your application
The request reaches you cleaned up, and that protects you first of all. An application that receives other people’s cookies and keys ends up writing them into its own log.
- The key. The
Authorizationheader stays with us. Your application never sees the key it was called with. - Cookies. They pass in neither direction, and that includes a
Set-Cookiesent by your application back to the caller. - The headers of our own entrance (
Host,X-Forwarded-*). They say something about us rather than about the request, and would confuse you when you try to tell where a call came from. - We pass on only
Content-Type,Accept,Accept-Language,Idempotency-Key,X-Request-Id.
Limits
The limits below are the same for everyone, ourselves included. If they get in the way of your everyday work, write to us and we will raise them. There is no need to look for workarounds.
| What | How much | Why |
|---|---|---|
| Requests per key | 60 a minute, 5000 a day | If a key leaks, the limit keeps the damage small. |
| Requests per account | 120 a minute | So that the limit above cannot be dodged with ten keys. |
| Request size | 256 KB | Large files do not go through here, and if you try, we tell you plainly. |
| Response size | 1 MB | The same, in the other direction. |
| Time per call | 25 s for AI, 20 s for the bridge | After that you get an error and can stop waiting. |
| Live keys per account | 20 | Any more would be hard to keep an eye on in one account. |
When something does not work
Every error comes with a short code for the program and a sentence for the
person. The code is in the code field. Have your program read that
field, because the wording of the text may change.
- You will never get a 403 or a 404 from us. The network in front of the site turns both into a page instead of an answer, so we send refusals as 401 or 400, with the precise reason in
code.
| Status | Code | What it means |
|---|---|---|
| 401 | bad_key |
The key is wrong, revoked, expired or not allowed to do this. Issue a new one in the portal. |
| 401 | wrong_project |
The key belongs to a different project. Each key belongs to one. |
| 401 | ip_not_allowed |
The key is locked to other addresses. Change the list in the portal. |
| 401 | account_blocked |
Access to the account is suspended. Get in touch. |
| 400 | bad_json |
The body is not valid JSON. |
| 400 | unknown_model |
No such model. The names are at /v1/models. |
| 400 | model_not_allowed |
That model is not offered. The list is at /v1/models. |
| 400 | stream_unsupported |
You sent "stream": true. Remove it, as streaming is not available. |
| 400 | not_found |
No such address. Check the path. |
| 400 | target_unverified |
The application address has not been proved in the portal yet. |
| 402 | no_wallet |
The account has no credit wallet. |
| 402 | insufficient_credits |
Not enough credits for this request. Nothing was spent; top up in the portal. |
| 402 | unpaid_calls |
Earlier calls are still unpaid. Top up and they settle by themselves. |
| 402 | balance_unavailable |
The balance cannot be checked right now. Try again shortly. |
| 402 | key_limit_reached |
This key has reached its monthly cap. |
| 409 | no code | Your application answered 403 or 404. The real number is in X-AICLOUD-Upstream-Status. |
| 413 | too_large |
The request is over 256 KB. |
| 429 | rate_limited |
Too many requests. Wait the seconds in Retry-After. |
| 502 | model_error |
The model refused the request. Its own reason is in detail. Not billed. |
| 502 | target_unreachable |
The bridge did not reach your application. Usually the address is wrong or not responding. |
| 502 | response_too_large |
Your application returned more than 1 MB. |
| 503 | gateway_off |
The entrance is temporarily switched off by us. Try again shortly. |
| 500 | internal |
Our fault. If it keeps happening, tell us. |
Security: what we do and what we ask of you
A key is a string written into another program, where it probably stays for years. We have taken every measure we can on our side, but two things are up to you.
- On our side: all we keep of the key is an irreversible hash. Even if the database leaked, nobody could get a working key out of it.
- On our side: the log records what was asked, how it ended and what it cost. It never keeps the content of your request, and never the key.
- On our side: a bridge request never travels to an internal network, even if the domain is repointed there after it was proved. We check this on every call.
- On your side: treat the key like a password. Keep it in an environment variable, not in the code or the repository.
- On your side: if you have a fixed address, put it in the key’s allowed-addresses list. Then, if someone steals it, they cannot use it from anywhere else.
- More on the measures: Data security.
Frequently asked questions
Do we need a programmer?
For the AI entrance, not necessarily. Whoever maintains your other program can usually get it to send a request. For the bridge you need someone to put the proof file in place and check the signature. If your application was built with us, you simply ask the studio agent to do it.
Can I see my key again?
No, and that is on purpose. We hold only its irreversible hash, and nobody, us included, can rebuild the key from it. If you have lost it, revoke it with one button and issue a new one.
What if the key leaks?
You revoke it in the portal and it stops working from the very next call. That is why it helps to give each program its own key: when you revoke one, the others keep working.
Do I pay for failed calls?
No. You pay only for what the model actually processed. If the request is refused, your credits have run out or you went over a limit, nothing is taken.
Can the API read and change the data in my project?
Only through your own application, and only as far as it allows. We give no direct access to the database. The bridge passes the request to your code, and your code decides what to do with it.
Issue your first key
You issue it in the portal, on the “API” screen, in a couple of minutes. You pay nothing until the first call.