API
API: connect your software to AI-CLOUD
If you already have an application with us, this is where you connect it to your other programs, such as the warehouse system or the accounting package, and to your website. The same place also gives you the AI models, charged to your credits. You can send this page straight to whoever looks after the other program.
Last revised: 2 September 2026
What it does
There are two entrances and they work with the same key. When you issue a 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 nor a key from the model vendor.
- 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 so you know it really came from us.
Getting started
It takes two minutes. A key can be issued by the owner or an administrator of the account. Members and viewers don’t have that right, since a key spends the whole account’s credits and works without anyone signing in.
- Sign in to the portal and open API from the menu.
- Press “Issue a key”, give it a name and pick the project and what it is for.
- The key is shown once. Save it straight away, because we don’t keep it and can’t show it to you again. If you lose it, you 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 goes in the
Authorization header, as with most APIs you have worked with.
curl https://ai-cloud.gr/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
Your program fetches the list from us each time, so an old copy never sits in its code. The prices in the answer are yours, meaning what you will actually be charged.
- Prices are in micro-credits per 1000 tokens. 1000 micro-credits = 1 credit.
- A token is roughly three to four Greek characters. A medium-length question together with its answer comes to a few hundred tokens.
- The models on offer are Anthropic’s, since this entrance takes their request format. If you need another vendor, write to us.
curl https://ai-cloud.gr/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 is the same one Anthropic accepts. If your program already talks to their API, you change only the address and the key. The answer is passed back to you exactly as it arrived, uncut.
max_tokenssets how long the answer may be. The most we accept is 4096, so you know in advance what the dearest possible call can cost.- Streaming (
"stream": true) is not supported. Such a request is refused with a message giving the reason, and we never quietly alter it. - Each call gets 25 seconds. If the model hasn’t answered within that time an error comes back, so your program is never left waiting indefinitely.
curl https://ai-cloud.gr/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 the cost of the call plus a 20% margin. The charge is worked out once the
answer is in, from the real token counts, and nothing is held back beforehand.
Before we send the request, however, we check whether your balance would cover its
most expensive possible outcome (your text plus the full max_tokens).
If it wouldn’t, the request is refused at once, so you are never left owing.
- 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 give them back in lower case.
- When your credits would not cover the most expensive outcome of a request, it is refused before it runs, so nothing is spent and no debt is created. The answer tells you how many credits are needed and how many you have.
- With 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 money, the charge just doesn’t drop to nothing.
- Each key can have a monthly cap in credits. Once it hits the cap only that key stops, and your other keys carry on as normal.
- The bridge to your application costs no credits. You already pay for the project’s hosting.
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. Because we sit between the two, you get a key you can revoke with one button, a limit on calls and a record of who called and when.
- The address is declared in the portal, on the API screen, per project.
- Only an address with
https://and a domain name is accepted. A numeric IP address cannot be declared. - Whatever comes after the project id is added to your address unchanged, query string included.
curl https://ai-cloud.gr/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
An address you declare is not switched on straight away. First you prove the domain belongs to you. Without that step, anyone could declare somebody else’s site and flood it with requests in our name and from our address. You prove it once, and it takes about 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 from the start. Proof for one domain never counts for any other.
Make /.well-known/aicloud-gateway.txt return this text
as plain text: aicloud-verify-xxxxxxxx
How your application knows it is us
Every call through the bridge is signed. Your application works out the same signature with the shared secret shown in the portal and compares the two. That way, even if someone guesses your address, they cannot pose as us.
- Along with the hash of the body, the time, the method and the path are signed. That is why a signature cannot be used again for another path.
- The path is exactly the one your server receives, with the query string and with the encoding it had on arrival. In Node that is
req.urlas it stands: do not decode it and do not cut off the query before computing the signature. - If your address has a prefix (
https://your-site.com/api), the prefix belongs to the signed path as well, just as it appears in the request that reaches you. - You can see the secret in the portal whenever you like and replace it with one button, at which point the old one stops working at once.
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
Before we hand the request on, we take a few things out of it, and we do it to protect you. 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 the
Set-Cookieyour application sends back to the caller. - The headers of our own entrance (
Host,X-Forwarded-*). They relate to our infrastructure and would confuse you about where the call came from. - The only headers passed on are
Content-Type,Accept,Accept-Language,Idempotency-Key,X-Request-Id.
Limits
The limits apply to everyone, including us. If they are too tight for your everyday work, write to us and we will raise them, since there is no way round them.
| 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 the line above cannot be sidestepped with ten keys. |
| Request size | 256 KB | Large files don’t go through here, and you are told so plainly with an error. |
| Response size | 1 MB | The same, in the other direction. |
| Time per call | 25 s for AI, 20 s for the bridge | After that time an error is returned. |
| Live keys per account | 20 | With more keys, an account loses track of which one is used where. |
When something does not work
Every error has a short code for the program and a sentence for the person. The
code is in the code field. Have your program check that, 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 those codes into a web page, so every refusal comes back 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. Top up in the portal. Nothing was spent. |
| 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 | — | 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 cannot be reached. |
| 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, often for years. That is why we protect it with every measure we can, and there are two things left to you.
- On our side: the key is stored only as an irreversible hash. Even if the database leaked, nobody would 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, nor the key.
- On our side: a bridge request is never sent into an internal network, even if the domain is pointed there after the proof. The check is repeated on every call.
- On your side: look after the key as you would a password, in an environment variable. Don’t write it into the code and don’t commit it to the repository.
- On your side: if you have a fixed address, put it in the key’s allowed-addresses list. Then a stolen key does not work from anywhere else.
- More on the measures: Data security.
Frequently asked questions
Do we need a programmer?
For the AI entrance, not necessarily. Whoever looks after your other program can usually get it to send a request. The bridge needs someone to upload the proof file and add the signature check. If your application was built with us, just ask the studio agent to do it.
Can I see my key again?
No, and we made it that way on purpose. We keep only its irreversible hash, so nobody can recover it, not even us. If you lose it, you 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. It is worth giving every program its own key, so revoking one leaves the rest running.
Do I pay for failed calls?
No. You are charged only for what the model actually processed. A request that was refused, say because the credits ran out or a limit was exceeded, costs you nothing.
Can the API read and change the data in my project?
Only through your own application, and only what it allows. We give no direct access to your database. The bridge hands the request to your code, and your code decides what happens.
Issue your first key
You issue the key in the portal, on the “API” screen. It takes two minutes, and nothing is charged until your first call.