Createya — AI Image & Video Generation

---

🎯 为什么需要它

AI Agent 时代已经到来。Claude、Cursor、Cline、OpenCode、Codex——每周都会出现一个新的 Agent 框架。它们都通过 MCP（Model Context Protocol）运行，这是 Anthropic 推出的连接外部工具的开放标准。

Createya 解决了 4 个常见问题：

问题	Createya 的解决方案
地理封锁，需要 VPN	可直接访问，无需 VPN
不接受境外银行卡	支持俄罗斯银行卡、快速支付系统（СБП）、T-Pay，可用卢布付款
多个服务需要使用不同密钥	通过一个 API 密钥访问模型目录
数据需在本地存储（152-ФЗ）	所有数据均存储在本地，完全符合相关法律
企业客户与 B2B	提供合同、账单和验收单。支持通过银行转账支付，并缴纳增值税

以上都可以通过 MCP（适用于 Agent）或普通 REST（适用于你自己的代码）使用。

---

⚡ 60 秒上手

1. 注册 → 免费获得 100 个积分 createya.ai

2. 创建 API 密钥（格式为 crya_sk_<32hex>） createya.ai/settings/api-keys

3. 接下来，选择你的方式：

🤖 如果你正在构建 AI Agent → 只需一条命令

curl -fsSL https://api.createya.ai/install | bash -s -- crya_sk_YOUR_KEY

一键安装 MCP 服务和技能。自动检测：Claude Code（~/.claude/skills/）、opencode（读取相同目录）、Codex CLI / Cursor / OpenClaw（按照 agentskills.io 标准使用通用路径 ~/.agents/skills/）。

仓库中的所有技能都会自动安装——新增技能后，下次运行 install 时就会自动安装。实用选项：

# Посмотреть какие скиллы есть:
curl -fsSL https://api.createya.ai/install | bash -s -- --list

# Поставить только конкретные:
curl -fsSL https://api.createya.ai/install | bash -s -- crya_sk_KEY --skills creative-director

→ 查看所有客户端的说明

💻 如果你在编写自己的代码 → REST

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":"кот на луне"}}'

→ 查看 curl / Python / Node.js / Go 完整示例

💡 启动即可免费获得 100 个积分。套餐和充值信息请访问网站：createya.ai。

---

🤖 MCP 服务能做什么

连接后，你的 Agent 将获得 4 个工具：

工具	说明
🔍 list_models	列出所有模型及其 parameters_schema 的目录。Agent 会自动了解可以调用哪些模型。
🎨 run_model	启动生成：{ model: <slug 或 family>, input: {...} }。支持图片 / 视频 / 音频 / 文本。
⏳ get_run_status	查询异步任务状态（视频通常需要 30-180 秒生成）。
💰 get_balance	查看 workspace 当前积分余额。

Endpoint： https://api.createya.ai/mcp 传输方式： Streamable HTTP（MCP 规范 2025-06-18） 授权方式： OAuth 2.1（适用于 Claude.ai）或 Bearer 请求头（适用于其他所有场景）

---

⚙️ 连接 — 选择你的工具

A. OAuth — 最简单的方式（Claude Desktop / Claude.ai / Claude Code）

1. Claude.ai → Settings → Connectors → Add custom connector Claude Desktop → + 菜单 → Connectors → Add custom connector
2. 服务器 URL：https://api.createya.ai/mcp
3. Claude 会打开 Createya 授权页面 — 粘贴你的 crya_sk_... 密钥 → 允许
4. 完成。工具（list_models、run_model...）会出现在聊天中。

💡 团队中的每位成员都应使用自己的密钥。费用从密钥关联的 workspace 中扣除。

B. Claude Code（CLI）

运行一个脚本 — 一次性安装 MCP 和技能：

curl -fsSL https://api.createya.ai/install | bash -s -- crya_sk_YOUR_KEY

或者只安装 MCP，不安装技能：

claude mcp add createya "https://api.createya.ai/mcp" \
  --transport http \
  --header "Authorization: Bearer crya_sk_..." \
  --scope user

C. Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目中）：

{
  "mcpServers": {
    "createya": {
      "url": "https://api.createya.ai/mcp",
      "headers": {
        "Authorization": "Bearer crya_sk_..."
      }
    }
  }
}

D. Cline（VS Code）

在 settings.json 中：

{
  "cline.mcpServers": {
    "createya": {
      "type": "streamableHttp",
      "url": "https://api.createya.ai/mcp",
      "headers": { "Authorization": "Bearer crya_sk_..." },
      "disabled": false
    }
  }
}

类型为 streamableHttp（驼峰命名，不带连字符）。

E. Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "createya": {
      "serverUrl": "https://api.createya.ai/mcp",
      "headers": { "Authorization": "Bearer crya_sk_..." }
    }
  }
}

F. OpenAI Codex

直接使用 MCP — 将 configs/codex.toml 中的模板添加到 ~/.codex/config.toml：

[mcp_servers.createya]
url = "https://api.createya.ai/mcp"
http_headers = { Authorization = "Bearer crya_sk_..." }
enabled = true

Codex 插件 — 插件位于 plugins/createya-mcp/。它会在 Codex Plugins UI 中添加 Createya 卡片、徽标、MCP 服务，以及仓库中的所有 Createya 技能。详细说明：docs/codex-plugin.md。

根目录下的 skills/ 是唯一可信来源。编辑技能或资源文件后，更新插件包：

scripts/sync-codex-plugin.sh

CI 会检查 plugins/createya-mcp/skills/ 和 plugins/createya-mcp/assets/ 是否与根目录内容一致。

Codex Desktop：

1. 打开 Codex → Plugins → Add marketplace。
2. 在 来源 字段中粘贴 Createya-ai/Createya-mcp。
3. 保持 Git ref 不变。
4. 选择性路径 留空。
5. 点击 Add marketplace，找到 Createya 并安装插件。

通过终端：

codex plugin marketplace add Createya-ai/Createya-mcp

从仓库克隆目录进行本地验证：

codex plugin marketplace add /path/to/Createya-mcp

安装后完成 Createya 授权。

G. OpenCode

参见 configs/opencode.json — 可直接使用的模板。

H. 其他任意 MCP 客户端

可直接使用的配置位于 configs/ 文件夹中。复制所需配置，将 crya_sk_... 替换为你的密钥即可。

---

🎨 模型目录

包含 curl/Python/Node.js 示例的完整最新文档位于单独的子域名 docs.createya.ai/models/（每周与 live API 同步）。

当前可通过 MCP/REST 公开使用（5 个 endpoints）

模型	类型	Slug	详情
Nano Banana 2	图像	nano-banana-2	docs.createya.ai/models/nano-banana-2
Nano Banana 2 Edit	图像（i2i）	nano-banana-2-edit	docs.createya.ai/models/nano-banana-2-edit
Nano Banana Pro	图像	nano-banana-pro	docs.createya.ai/models/nano-banana-pro
GPT Image 2	图像	gpt-image-2	docs.createya.ai/models/gpt-image-2
GPT Image 2 Edit	图像（i2i）	gpt-image-2-edit	docs.createya.ai/models/gpt-image-2-edit

即将推出（140+ 个 endpoints）

正在逐步开放其他系列的公开访问： 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 等。

📚 通过 API 获取 实时目录：GET https://api.createya.ai/v1/models（公开，无需 auth） 📖 模型的 营销概览：createya.ai/knowledge 📡 API 文档 + 各模型页面：docs.createya.ai

---

💡 使用示例

生成图片

Ты: Сгенерируй картинку через Createya — кот на луне в стиле Studio Ghibli, формат 16:9
Агент: [вызывает createya:run_model с model=nano-banana-2]
       → возвращает CDN-ссылку на изображение

examples/01-generate-image.md — 更多详情。

生成视频

Ты: Возьми эту картинку (URL) и оживи через Kling, 5 секунд
Агент: [вызывает createya:run_model с model=kling-video-o3, image_url=...]
       → возвращает run_id
       → через 30-60 сек: createya:get_run_status → готовое видео

examples/02-generate-video.md

不使用 MCP 的 REST

• examples/05-rest-curl.md — curl（同步 + 异步 + 上传）
• examples/06-rest-python.md — Python 客户端
• examples/07-rest-nodejs.md — TypeScript / Node.js / Express / Next.js
• examples/08-rest-go.md — Go（标准库，无依赖）
• examples/09-rest-php.md — PHP / Laravel / Symfony
• examples/03-async-polling.md — 带指数退避的异步任务（视频）
• examples/04-upload-image.md — 上传图片，用于图生图
• examples/10-error-handling.md — 处理所有错误，重试模式

---

📡 不使用 MCP — 普通 REST API

如果你不是 Agent，只是开发者，也可以使用 REST API。一个 Bearer 令牌，一个 POST 请求，搞定。

步骤 1 — 获取令牌

1. 在 createya.ai 注册（可获得 100 个免费额度）
2. 访问 createya.ai/settings/api-keys
3. Create new key → 为其命名（例如 my-bot-prod）→ Create
4. 复制密钥 — 它只会显示一次。格式：crya_sk_<32hex>
5. 像密码一样保管（环境变量、密钥管理器，不要放进 git）

步骤 2 — 发起第一个请求

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": "кот на луне в стиле Studio Ghibli",
      "aspect_ratio": "16:9"
    }
  }'

响应：

{
  "run_id": "run_01HZX...",
  "status": "completed",
  "output": {
    "urls": ["https://cdn-new.createya.ai/image/profile-id/abc123.png"]
  }
}

步骤 3 — Python / Node.js / Go

Python（使用 requests）：

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": "кот на луне"}}
)
print(r.json()["output"]["urls"][0])

Node.js（原生 fetch，Node 18+）：

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: "кот на луне" }
  })
});
const json = await r.json();
console.log(json.output.urls[0]);

Go：

body := strings.NewReader(`{"model":"nano-banana-2","input":{"prompt":"кот на луне"}}`)
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)

→ 完整示例：examples/05-rest-curl.md、examples/06-rest-python.md、examples/07-rest-nodejs.md

异步任务（视频、长时音乐）

# Шаг 1 — запуск
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" }

# Шаг 2 — polling каждые 10 сек
curl https://api.createya.ai/v1/runs/run_01J2... \
  -H "Authorization: Bearer crya_sk_..."
# → { "status": "completed", "output": { "url": "https://cdn-new.createya.ai/video/..." } }

所有 REST 端点

方法	URL	功能
GET	/v1/models	所有模型的目录，包含 parameters_schema
POST	/v1/run	启动生成
GET	/v1/runs/{run_id}	异步任务状态
GET	/v1/balance	工作区额度余额
POST	/v1/uploads	将图片/视频上传到 Createya CDN（用于图生图）
GET	/v1/openapi.json	OpenAPI 3.1 规范（用于自动生成 SDK）

机器可读规范

• OpenAPI 3.1：https://api.createya.ai/v1/openapi.json — 用于自动生成 Python/TypeScript/Java/Ruby SDK
• llms.txt：https://api.createya.ai/llms.txt — 面向 AI Agent 的 API 索引
• 完整文档：createya.ai/api

---

🏢 面向企业客户

Createya 可与企业签订合同并通过银行转账结算。

• 银行转账 — 开具发票，由公司账户付款
• 合同 + 验收单 — 提供会计所需的结算文件
• 增值税 — 可按要求开具含税或不含税发票
• 大额套餐 — 批量折扣可单独协商
• 高负载 API — 更高的速率限制，为各服务提供专用密钥
• 152-FZ — 所有数据均存储在本地，完全符合《个人数据法》
• 白标 — 可提供使用你品牌的 Telegram 机器人 / web 端

📩 一个工作日内提供公司信息和发票：[email protected]

---

🔐 安全性

• API 密钥 — 格式为 crya_sk_<32hex>，以哈希形式存储（bcrypt）
• 工作区隔离 — 密钥绑定到单个工作区，无法扣除其他工作区的额度
• OAuth 2.1 + PKCE — 适用于 Web 客户端（Claude.ai）
• 速率限制 — 按密钥设置，防止密钥泄露造成损失
• 152-FZ — 所有数据均存储在本地

---

📚 Документация

Документ	Где
Quickstart REST	createya.ai/api/getting-started
Полная REST-спека	createya.ai/api/rest
MCP-коннектор	createya.ai/api/mcp
OpenAPI 3.1	api.createya.ai/v1/openapi.json
Каталог моделей	createya.ai/knowledge
Примеры в этом репо	examples/

---

💬 Связь

• 🌐 Сайт: createya.ai
• 📚 База знаний: createya.ai/knowledge
• 🤖 Telegram-бот (для генерации напрямую без кода): @createya_bot
• 📧 Поддержка: [email protected]
• 💼 Партнёрство / Амбассадорам: createya.ai/ambassador

---

🤝 Контрибьютим

PRs welcome — новый MCP-клиент конфиг, новый язык в примерах, фикс опечатки. См. CONTRIBUTING.md для guideline'ов.

Нашёл баг или хочешь модель — открой issue.

Уязвимость? Не открывай публичный issue — пиши на [email protected]. См. SECURITY.md.

---

📄 Лицензия

MIT — бери, форкай, делай свои интеграции. Только укажи нас как автора.

---