Content
<div align="center">
<img src="assets/logo.png" alt="Createya" width="320"/>
# Createya MCP & API
### A world of neural networks without borders.
#### Via MCP or REST. 100+ models. One key.
[](https://modelcontextprotocol.io/)
[](https://api.createya.ai/v1/openapi.json)
[](LICENSE)
[]()
[](docs/models-image.md)
[🚀 Quick Start](#-quick-start) · [🤖 MCP](#-what-does-the-mcp-server-do) · [📡 REST](#-without-mcp--regular-rest-api) · [🎨 Models](#-model-catalog) · [⚙️ Connection](#-connection) · [🏢 For Legal Entities](#-for-legal-entities) · [💬 Support](#-support)
---
**Connect Createya neural networks to your AI agent via MCP or to your code via REST. 100 free credits to get started.**
**Two paths to choose from:**
- 🤖 **MCP** — for AI agents (Claude, Cursor, Cline, Windsurf, Codex, OpenCode). One URL, OAuth or Bearer — and the agent sees the model catalog itself.
- 📡 **REST** — for your code. One Bearer token, `POST /v1/run`, ready-to-use examples in curl / Python / Node.js / Go.
</div>
---
## 🎯 Why is this needed
The era of AI agents has arrived. Claude, Cursor, Cline, OpenCode, Codex — a new agent framework appears every week. They all work through **MCP** (Model Context Protocol) — an open standard from Anthropic for connecting external tools.
Createya solves 4 typical problems:
| Problem | Createya Solution |
|---|---|
| Geoblocking and VPN required | Direct access — no VPN required |
| Foreign cards not accepted | Russian cards, SBP, T-Pay — payment in rubles |
| Dozens of services with different keys | Model catalog via **one API key** |
| Local data storage (152-FZ) | All data stored locally, full compliance with the law |
| Legal entities and B2B | Contract, invoice, act. Payment by non-cash transfer with VAT |
And all this — through **MCP** (for agents) or regular **REST** (for your code).
---
## ⚡ Quick Start
**1. Register → get 100 free credits**
[createya.ai](https://createya.ai)
**2. Create an API key** (format `crya_sk_<32hex>`)
[createya.ai/settings/api-keys](https://createya.ai/settings/api-keys)
**3. Next — choose your path:**
### 🤖 If you're building an AI agent → one command
```bash
curl -fsSL https://api.createya.ai/install | bash -s -- crya_sk_YOUR_KEY
```
Installs MCP server + skills in one go. Auto-detection: Claude Code (`~/.claude/skills/`), opencode (reads the same), Codex CLI / Cursor / OpenClaw (universal path `~/.agents/skills/` according to the [agentskills.io](https://agentskills.io) standard).
All skills from the repository are installed automatically — add a new one = it appears on the next `install`. Useful flags:
```bash
# List available skills:
curl -fsSL https://api.createya.ai/install | bash -s -- --list
# Install specific skills only:
curl -fsSL https://api.createya.ai/install | bash -s -- crya_sk_KEY --skills creative-director
```
[→ Instructions for all clients](#-connection)
### 💻 If you're writing your own code → REST
```bash
curl -X POST https://api.createya.ai/v1/run \
-H "Authorization: Bearer crya_sk_..." \
-H "Content-Type: application/json" \
-d '{"model":"nano-banana-2","input":{"prompt":"cat on the moon"}}'
```
[→ Full examples in curl / Python / Node.js / Go](#-without-mcp--regular-rest-api)
> 💡 **100 free credits** to get started. Tariffs and replenishment — on the website: [createya.ai](https://createya.ai).
---
## 🤖 What does the MCP server do
After connecting, your agent gets **4 tools**:
| Tool | Description |
|---|---|
| 🔍 **`list_models`** | Catalog of all models with `parameters_schema`. The agent learns what it can call. |
| 🎨 **`run_model`** | Launch generation: `{ model: <slug or family>, input: {...} }`. Image / video / audio / text. |
| ⏳ **`get_run_status`** | Check the status of an async task (video usually takes 30-180 seconds). |
| 💰 **`get_balance`** | Current balance of workspace credits. |
**Endpoint:** `https://api.createya.ai/mcp`
**Transport:** Streamable HTTP (MCP spec 2025-06-18)
**Authorization:** OAuth 2.1 (for Claude.ai) or Bearer header (for everything else)
---
## ⚙️ Connection — choose your tool
### A. OAuth — the easiest way (Claude Desktop / Claude.ai / Claude Code)
1. **Claude.ai** → [Settings → Connectors](https://claude.ai/settings/connectors) → **Add custom connector**
**Claude Desktop** → menu `+` → `Connectors` → `Add custom connector`
2. Server URL: `https://api.createya.ai/mcp`
3. Claude will open the Createya authorization page — insert your `crya_sk_...` key → **Allow**
4. Done. Tools (`list_models`, `run_model`...) will appear in the chat.
> 💡 Each team member — their own key. Credits are deducted from the workspace to which the key is linked.
### B. Claude Code (CLI)
**One script — installs MCP and skills at once:**
```bash
curl -fsSL https://api.createya.ai/install | bash -s -- crya_sk_YOUR_KEY
```
Or only MCP, without skills:
```bash
claude mcp add createya "https://api.createya.ai/mcp" \
--transport http \
--header "Authorization: Bearer crya_sk_..." \
--scope user
```
### C. Cursor
`~/.cursor/mcp.json` (globally) or `.cursor/mcp.json` (in the project):
```json
{
"mcpServers": {
"createya": {
"url": "https://api.createya.ai/mcp",
"headers": {
"Authorization": "Bearer crya_sk_..."
}
}
}
}
```
### D. Cline (VS Code)
In `settings.json`:
```json
{
"cline.mcpServers": {
"createya": {
"type": "streamableHttp",
"url": "https://api.createya.ai/mcp",
"headers": { "Authorization": "Bearer crya_sk_..." },
"disabled": false
}
}
}
```
> Type — `streamableHttp` (camelCase, without a hyphen).
### E. Windsurf
`~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"createya": {
"serverUrl": "https://api.createya.ai/mcp",
"headers": { "Authorization": "Bearer crya_sk_..." }
}
}
}
```
### F. OpenAI Codex
**MCP directly** — add the template from [`configs/codex.toml`](configs/codex.toml) to `~/.codex/config.toml`:
```toml
[mcp_servers.createya]
url = "https://api.createya.ai/mcp"
http_headers = { Authorization = "Bearer crya_sk_..." }
enabled = true
```
**Codex plugin** — the plugin is located in [`plugins/createya-mcp/`](plugins/createya-mcp/). It adds a Createya card to the Codex Plugins UI, logo, MCP server, and all Createya skills from the repository. Detailed instructions: [`docs/codex-plugin.md`](docs/codex-plugin.md).
`skills/` in the root — source of truth. After editing skills or assets, update the plugin package:
```bash
scripts/sync-codex-plugin.sh
```
CI checks that `plugins/createya-mcp/skills/` and `plugins/createya-mcp/assets/` do not diverge from the root.
Codex Desktop:
1. Open Codex → Plugins → Add marketplace.
2. In the **Source** field, insert `Createya-ai/Createya-mcp`.
3. Do not change **Git ref**.
4. Leave **Selective paths** empty.
5. Click **Add marketplace**, find **Createya**, and install the plugin.
Via terminal:
```bash
codex plugin marketplace add Createya-ai/Createya-mcp
```
Local check from a repository clone:
```bash
codex plugin marketplace add /path/to/Createya-mcp
```
After installation, go through Createya authorization.
### G. OpenCode
See [`configs/opencode.json`](configs/opencode.json) — a ready-made template.
### H. Any other MCP client
Ready-made configs — in the [`configs/`](configs/) folder. Copy the necessary one, replace `crya_sk_...` with your key — and you're done.
---
## 🎨 Model Catalog
Full up-to-date documentation with examples in curl/Python/Node.js — on a separate subdomain **[docs.createya.ai/models/](https://docs.createya.ai/models/)** (synchronized with live API once a week).
### Currently publicly available via MCP/REST (5 endpoints)
| Model | Type | Slug | Details |
|---|---|---|---|
| **Nano Banana 2** | image | `nano-banana-2` | [docs.createya.ai/models/nano-banana-2](https://docs.createya.ai/models/nano-banana-2) |
| **Nano Banana 2 Edit** | image (i2i) | `nano-banana-2-edit` | [docs.createya.ai/models/nano-banana-2-edit](https://docs.createya.ai/models/nano-banana-2-edit) |
| **Nano Banana Pro** | image | `nano-banana-pro` | [docs.createya.ai/models/nano-banana-pro](https://docs.createya.ai/models/nano-banana-pro) |
| **GPT Image 2** | image | `gpt-image-2` | [docs.createya.ai/models/gpt-image-2](https://docs.createya.ai/models/gpt-image-2) |
| **GPT Image 2 Edit** | image (i2i) | `gpt-image-2-edit` | [docs.createya.ai/models/gpt-image-2-edit](https://docs.createya.ai/models/gpt-image-2-edit) |
### Coming soon (140+ endpoints)
Under development — opening public access to the remaining families:
**FLUX 2 / Kontext** · **Sora 2** · **Veo 3.1** / Fast · **Kling Video O3 / V3 / 4K** · **Seedance 2.0** · **Happy Horse** · **Hailuo 2.3** · **Higgsfield Soul** · **Midjourney** · **Runway Gen-4** · **Recraft** · **Ideogram** · **Imagen** · **Wan** · **Grok Imagine** · **Seedream** and others.
📚 **Live catalog** via API: `GET https://api.createya.ai/v1/models` (public, no auth)
📖 **Marketing overview** of models: [createya.ai/knowledge](https://createya.ai/knowledge)
📡 **API documentation** + per-model pages: [docs.createya.ai](https://docs.createya.ai)
---
## 💡 Usage Examples
### Generate an image
```
You: Generate an image through Createya — a cat on the moon in the style of Studio Ghibli, 16:9 format
Agent: [calls createya:run_model with model=nano-banana-2]
→ returns CDN link to the image
```
[`examples/01-generate-image.md`](examples/01-generate-image.md) — more details.
### Generate a video
```
You: Take this image (URL) and animate it with Kling, 5 seconds
Agent: [calls createya:run_model with model=kling-video-o3, image_url=...]
→ returns run_id
→ after 30-60 seconds: createya:get_run_status → ready video
```
[`examples/02-generate-video.md`](examples/02-generate-video.md)
### REST without MCP
- [`examples/05-rest-curl.md`](examples/05-rest-curl.md) — curl (sync + async + upload)
- [`examples/06-rest-python.md`](examples/06-rest-python.md) — Python client
- [`examples/07-rest-nodejs.md`](examples/07-rest-nodejs.md) — TypeScript / Node.js / Express / Next.js
- [`examples/08-rest-go.md`](examples/08-rest-go.md) — Go (stdlib, without dependencies)
- [`examples/09-rest-php.md`](examples/09-rest-php.md) — PHP / Laravel / Symfony
- [`examples/03-async-polling.md`](examples/03-async-polling.md) — async tasks (video) with exponential backoff
- [`examples/04-upload-image.md`](examples/04-upload-image.md) — uploading an image for image-to-image
- [`examples/10-error-handling.md`](examples/10-error-handling.md) — handling all errors, retry-pattern
---
## 📡 Without MCP — regular REST API
If you're not an agent, but just a developer — there's a REST API. One Bearer token, one POST, done.
### Step 1 — get a token
1. Register on [createya.ai](https://createya.ai) (get 100 free credits)
2. Go to [createya.ai/settings/api-keys](https://createya.ai/settings/api-keys)
3. **Create new key** → give it a name (e.g., `my-bot-prod`) → **Create**
4. **Copy the key** — it's shown **once**. Format: `crya_sk_<32hex>`
5. Store it like a password (env var, secret manager, not in git)
### Step 2 — first request
```bash
curl -X POST https://api.createya.ai/v1/run \
-H "Authorization: Bearer crya_sk_..." \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"input": {
"prompt": "a cat on the moon in the style of Studio Ghibli",
"aspect_ratio": "16:9"
}
}'
```
**Response:**
```json
{
"run_id": "run_01HZX...",
"status": "completed",
"output": {
"urls": ["https://cdn-new.createya.ai/image/profile-id/abc123.png"]
}
}
```
### Step 3 — Python / Node.js / Go
**Python** (with `requests`):
```python
import os, requests
KEY = os.environ["CREATEYA_API_KEY"]
r = requests.post(
"https://api.createya.ai/v1/run",
headers={"Authorization": f"Bearer {KEY}"},
json={"model": "nano-banana-2", "input": {"prompt": "a cat on the moon"}}
)
print(r.json()["output"]["urls"][0])
```
**Node.js** (native fetch, Node 18+):
```javascript
const KEY = process.env.CREATEYA_API_KEY;
const r = await fetch("https://api.createya.ai/v1/run", {
method: "POST",
headers: {
"Authorization": `Bearer ${KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "nano-banana-2",
input: { prompt: "a cat on the moon" }
})
});
const json = await r.json();
console.log(json.output.urls[0]);
```
**Go**:
```go
body := strings.NewReader(`{"model":"nano-banana-2","input":{"prompt":"a cat on the moon"}}`)
req, _ := http.NewRequest("POST", "https://api.createya.ai/v1/run", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CREATEYA_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
```
→ Full examples: [`examples/05-rest-curl.md`](examples/05-rest-curl.md), [`examples/06-rest-python.md`](examples/06-rest-python.md), [`examples/07-rest-nodejs.md`](examples/07-rest-nodejs.md)
### Async tasks (video, long music)
```bash
# Step 1 — launch
curl -X POST https://api.createya.ai/v1/run \
-H "Authorization: Bearer crya_sk_..." \
-H "Content-Type: application/json" \
-d '{"model":"kling-video-o3","input":{"image_url":"https://...","duration":5}}'
# → 202 Accepted, { "run_id": "run_01J2...", "status": "queued" }
# Step 2 — polling every 10 seconds
curl https://api.createya.ai/v1/runs/run_01J2... \
-H "Authorization: Bearer crya_sk_..."
# → { "status": "completed", "output": { "url": "https://cdn-new.createya.ai/video/..." } }
```
### All REST endpoints
| Method | URL | What it does |
|---|---|---|
| `GET` | `/v1/models` | Catalog of all models with `parameters_schema` |
| `POST` | `/v1/run` | Run generation |
| `GET` | `/v1/runs/{run_id}` | Status of async task |
| `GET` | `/v1/balance` | Workspace credit balance |
| `POST` | `/v1/uploads` | Upload image/video to Createya CDN (for image-to-image) |
| `GET` | `/v1/openapi.json` | OpenAPI 3.1 spec (for SDK autogeneration) |
### Machine-readable specs
- **OpenAPI 3.1**: `https://api.createya.ai/v1/openapi.json` — for autogeneration of Python/TypeScript/Java/Ruby SDK
- **llms.txt**: `https://api.createya.ai/llms.txt` — API map for AI agents
- **Full documentation**: [createya.ai/api](https://createya.ai/api)
---
## 🏢 For legal entities
Createya works with companies under a contract and without cash.
- **Non-cash settlement** — we issue an invoice, payment from the company's settlement account
- **Contract + act** — closing documents for accounting
- **VAT** — invoices with VAT or without, upon request
- **Volume packages** — wholesale discount is discussed individually
- **API under load** — increased rate limits, dedicated keys for services
- **152-FZ** — all data is stored locally, full compliance with the law "On Personal Data"
- **White-label** — Telegram bot / web under your brand is possible
📩 Details and account for 1 business day: [support@createya.ai](mailto:support@createya.ai)
---
## 🔐 Security
- **API keys** — format `crya_sk_<32hex>`, stored hashed (bcrypt)
- **Workspace isolation** — key is tied to one workspace, cannot spend credits from another
- **OAuth 2.1 + PKCE** — for web clients (Claude.ai)
- **Rate limits** — at the key level, protection against leaks
- **152-FZ** — all data is stored locally
---
## 📚 Documentation
| Document | Where |
|---|---|
| Quickstart REST | [createya.ai/api/getting-started](https://createya.ai/api/getting-started) |
| Full REST spec | [createya.ai/api/rest](https://createya.ai/api/rest) |
| MCP connector | [createya.ai/api/mcp](https://createya.ai/api/mcp) |
| OpenAPI 3.1 | [api.createya.ai/v1/openapi.json](https://api.createya.ai/v1/openapi.json) |
| Model catalog | [createya.ai/knowledge](https://createya.ai/knowledge) |
| Examples in this repo | [`examples/`](examples/) |
---
## 💬 Contact
- 🌐 **Website:** [createya.ai](https://createya.ai)
- 📚 **Knowledge base:** [createya.ai/knowledge](https://createya.ai/knowledge)
- 🤖 **Telegram bot** (for direct generation without code): [@createya_bot](https://t.me/createya_bot)
- 📧 **Support:** [support@createya.ai](mailto:support@createya.ai)
- 💼 **Partnership / Ambassadors:** [createya.ai/ambassador](https://createya.ai/ambassador)
---
## 🤝 Contributing
PRs welcome — new MCP client config, new language in examples, fix a typo. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Found a bug or want a model — open an [issue](https://github.com/Createya-ai/createya-mcp/issues/new/choose).
Vulnerability? Don't open a public issue — write to [security@createya.ai](mailto:security@createya.ai). See [SECURITY.md](SECURITY.md).
---
## 📄 License
[MIT](LICENSE) — take, fork, make your integrations. Just mention us as the author.
---
<div align="center">
**Createya — a world of neural networks without borders. For AI agents of the whole world.**
⭐ Star if this repo helped!
</div>
