Shape U API — Документация | Доступ к 50+ AI моделям через API

Быстрый старт

Shape U API полностью совместим с OpenAI SDK. Используйте любой OpenAI-совместимый клиент.

Создайте API-ключ в мини-приложении (Профиль → Platform API Keys)
Укажите base_url = https://api.shapeu.io/v1
Выберите модель и отправьте запрос

Python

Node.js

cURL

bash
pip install openai

pythonКопировать
from openai import OpenAI

client = OpenAI(
    api_key="sk-shapeu-your-key-here",
    base_url="https://api.shapeu.io/v1"
)

response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[
        {"role": "user", "content": "Привет! Расскажи о себе."}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

bash
npm install openai

javascriptКопировать
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-shapeu-your-key-here',
  baseURL: 'https://api.shapeu.io/v1',
});

const stream = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [
    { role: 'user', content: 'Привет! Расскажи о себе.' }
  ],
  stream: true,
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(text);
}

bashКопировать
curl https://api.shapeu.io/v1/chat/completions \
  -H "Authorization: Bearer sk-shapeu-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Привет!"}],
    "stream": false
  }'

Аутентификация

Все запросы к API требуют ключ в заголовке Authorization.

http
Authorization: Bearer sk-shapeu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡

Безопасность — ключ отображается только один раз при создании. Храните его безопасно. При компрометации — деактивируйте ключ в настройках.

Получение ключа

Откройте Shape U мини-приложение
Перейдите в Профиль → Platform API Keys
Нажмите «Создать ключ»
Скопируйте и сохраните ключ (он показывается один раз!)

Chat Completions

POST /v1/chat/completions Текстовая генерация. Поддержка streaming и файлов.

Параметры запроса

Параметр	Тип	Описание
modelrequired	string	ID модели (gpt-5-mini, claude-sonnet-4, gemini-2.5-pro...)
messagesrequired	array	Массив сообщений [{role, content}]. Поддержка multimodal content.
streamoptional	boolean	SSE streaming ответа. По умолчанию false.
temperatureoptional	number	Креативность (0.0 – 2.0)
max_tokensoptional	integer	Максимум токенов в ответе
file_idsoptional	array	Массив ID загруженных файлов для прикрепления к запросу

Пример ответа

jsonКопировать
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1739270400,
  "model": "gpt-5-mini",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Привет! Я AI-ассистент..." },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 45,
    "total_tokens": 57
  },
  "shapeu_usage": { "tokens_spent": 3, "file_tokens": 0 }
}

Image Generations

POST /v1/images/generations Генерация изображений по описанию.

Параметр	Тип	Описание
promptrequired	string	Описание изображения
modeloptional	string	Модель (dall-e-3, stable-diffusion-xl, flux-pro...). По умолчанию dall-e-3
sizeoptional	string	Размер (1024x1024, 1024x1792, 1792x1024)
noptional	integer	Количество изображений (1–4)

pythonКопировать
response = client.images.generate(
    model="dall-e-3",
    prompt="Космический кот в стиле Ван Гога",
    size="1024x1024"
)
print(response.data[0].url)

Files

POST /v1/files Загрузить файл (multipart/form-data).

Параметр	Тип	Описание
filerequired	file	Файл (multipart). Изображения, PDF, текст, код.
purposeoptional	string	Назначение: vision, assistants, general. По умолчанию general.

bashКопировать
curl https://api.shapeu.io/v1/files \
  -H "Authorization: Bearer sk-shapeu-your-key" \
  -F file=@screenshot.png \
  -F purpose=vision

Ответ

json
{
  "id": "f_abc123def456",
  "object": "file",
  "bytes": 245120,
  "created_at": 1739270400,
  "filename": "screenshot.png",
  "purpose": "vision",
  "status": "processed",
  "shapeu": {
    "mime_type": "image/png",
    "estimated_cost": 8,
    "expires_in_seconds": 1800,
    "is_image": true
  }
}

GET /v1/files Список активных файлов.

bash
curl https://api.shapeu.io/v1/files \
  -H "Authorization: Bearer sk-shapeu-your-key"

DELETE /v1/files/:id Удалить файл из хранилища.

bash
curl -X DELETE https://api.shapeu.io/v1/files/f_abc123 \
  -H "Authorization: Bearer sk-shapeu-your-key"

json
{ "id": "f_abc123", "object": "file", "deleted": true }

Models

GET /v1/models Список всех доступных моделей с ценами.

bash
curl https://api.shapeu.io/v1/models \
  -H "Authorization: Bearer sk-shapeu-your-key"

Каждая модель включает расширенные метаданные Shape U: тип, провайдер, тир, стоимость, поддержка vision.

Balance

GET /v1/balance Быстрая проверка баланса токенов.

Лёгкий эндпоинт для проверки текущего баланса. Не требует параметров.

bashКопировать
curl https://api.shapeu.io/v1/balance \
  -H "Authorization: Bearer sk-shapeu-your-key"

Пример ответа

json
{
  "object": "balance",
  "total": 4500,
  "available": 4500,
  "reserved": 0,
  "breakdown": {
    "subscription": 2500,
    "purchased": 1000,
    "bonus": 500,
    "daily_regen": 0
  },
  "plan": "pro",
  "plan_expires_at": "2026-03-15T00:00:00Z",
  "currency": {
    "name": "Shape U Token",
    "value_usd": 0.0015
  }
}

Использование в коде

Python

Node.js

pythonКопировать
import requests

resp = requests.get(
    "https://api.shapeu.io/v1/balance",
    headers={"Authorization": "Bearer sk-shapeu-your-key"}
)
data = resp.json()

print(f"Баланс: {data['total']} токенов")
print(f"План: {data['plan']}")

# Проверка перед запросом
if data["available"] < 10:
    print("⚠️ Мало токенов! Пополните баланс.")

javascriptКопировать
const resp = await fetch('https://api.shapeu.io/v1/balance', {
  headers: { 'Authorization': 'Bearer sk-shapeu-your-key' }
});
const data = await resp.json();

console.log(`Баланс: ${data.total} токенов`);
console.log(`План: ${data.plan}`);

if (data.available < 10) {
  console.warn('⚠️ Мало токенов! Пополните баланс.');
}

Поле	Тип	Описание
total	integer	Общий баланс токенов (все источники минус резерв)
available	integer	Доступно для использования (total, но не меньше 0)
reserved	integer	Зарезервировано под активные запросы
breakdown	object	Разбивка по источникам токенов
plan	string	Текущий план (free, starter, pro, ultra, ultimate)
plan_expires_at	string\|null	Дата окончания подписки (ISO 8601)

Usage

GET /v1/usage Расширенная статистика: баланс + данные API-ключа.

Полная информация о балансе, подписке и статистике использования API-ключа.

bashКопировать
curl https://api.shapeu.io/v1/usage \
  -H "Authorization: Bearer sk-shapeu-your-key"

Пример ответа

json
{
  "object": "usage",
  "balance": {
    "total": 4000,
    "subscription": 2500,
    "purchased": 1000,
    "bonus": 500,
    "daily_regen": 0,
    "reserved": 0
  },
  "subscription": {
    "plan": "pro",
    "expires_at": "2026-03-15T00:00:00Z"
  },
  "api_key": {
    "key_id": "key_...",
    "name": "My App",
    "usage_count": 142,
    "tokens_used": 850
  }
}

Работа с файлами

Shape U API поддерживает загрузку файлов для использования в запросах к моделям. Файлы можно прикреплять к /v1/chat/completions через параметр file_ids.

Поддерживаемые типы

Изображения — PNG, JPEG, GIF, WebP (для vision-моделей)
PDF — документы (требуется план Starter+)
Текст — TXT, CSV, JSON, XML, Markdown
Код — JS, TS, PY, HTML, CSS, Go, Rust, Java и др.

⚠️

Файлы хранятся 30 минут после загрузки и автоматически удаляются. Максимальный размер зависит от плана подписки (5–50 MB).

Пример: анализ изображения

pythonКопировать
from openai import OpenAI

client = OpenAI(
    api_key="sk-shapeu-your-key",
    base_url="https://api.shapeu.io/v1"
)

# 1. Загрузка файла
file = client.files.create(
    file=open("diagram.png", "rb"),
    purpose="vision"
)

# 2. Использование в chat completions
response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "Что изображено на этой диаграмме?"}
    ],
    extra_body={"file_ids": [file.id]}
)

print(response.choices[0].message.content)

Пример: анализ кода

bashКопировать
# 1. Загружаем файл
FILE_ID=$(curl -s https://api.shapeu.io/v1/files \
  -H "Authorization: Bearer sk-shapeu-your-key" \
  -F file=@main.py -F purpose=assistants | jq -r '.id')

# 2. Отправляем в chat completions
curl https://api.shapeu.io/v1/chat/completions \
  -H "Authorization: Bearer sk-shapeu-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role":"user","content":"Проанализируй код, найди баги"}],
    "file_ids": ["'$FILE_ID'"]
  }'

Inline Vision (OpenAI-совместимый формат)

Вместо file_ids вы также можете отправлять изображения прямо в поле content в формате multimodal:

pythonКопировать
import base64

with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Что на фото?"},
            {"type": "image_url", "image_url": {
                "url": f"data:image/jpeg;base64,{b64}"
            }}
        ]
    }]
)

Streaming (SSE)

Установите stream: true для получения ответа по частям через Server-Sent Events.

sse event
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Привет"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

📡

Формат полностью совместим с OpenAI SSE. Любой клиент, поддерживающий OpenAI streaming, будет работать без изменений.

Тарификация

Стоимость указывается в токенах Shape U. 1 токен ≈ $0.0015 USD. Стоимость зависит от модели и длины запроса.

Модель	Примерная стоимость	Тип
gpt-5-mini	~3 токена	Текст
gpt-5	~15 токенов	Текст
gpt-4o	~8 токенов	Текст + Vision
claude-sonnet-4	~10 токенов	Текст + Vision
gemini-2.5-pro	~5 токенов	Текст
dall-e-3	~40 токенов	Изображение
stable-diffusion-xl	~20 токенов	Изображение

💰

Используйте GET /v1/models для получения актуальных цен. Каждая модель содержит поле shapeu.token_cost.

Фактическая стоимость возвращается в поле shapeu_usage.tokens_spent ответа.

Обработка ошибок

Все ошибки возвращаются в OpenAI-совместимом формате:

json
{
  "error": {
    "message": "Описание ошибки",
    "type": "error_type",
    "code": "error_code"
  }
}

HTTP код	Тип	Описание
400	invalid_request_error	Некорректные параметры запроса
401	authentication_error	Невалидный или отсутствующий API-ключ
402	billing_error	Недостаточно токенов на балансе
403	permission_error	Модель недоступна для данного ключа/плана
429	rate_limit_error	Превышен лимит запросов
500	server_error	Внутренняя ошибка сервера
503	server_error	Провайдер временно недоступен

🔄

При ошибках 429 и 503 рекомендуется повторить запрос с экспоненциальной задержкой (exponential backoff).