Быстрое использование API

Quick Start

Короткий сценарий запуска API за 3 шага.

1. Зарегистрируйтесь в GIP VISION: Открыть страницу регистрации.
2. Откройте в личном кабинете (в web-версии) раздел Мои настройки и сгенерируйте API-токен.
3. Скачайте тестовые IFC-модели:
   • Тестовая модель 1: IFC Закладная деталь
   • Тестовая модель 2: Кабинет 26 R26

Разместить на плоскости

Endpoint: POST /api/gip-vision/v1/session/by_plane/
Файл: ifc-zakladnaya-detail-mn557-21-06-2026.ifc
Примечание: заголовок X-API-Key опционален, если вы не планируете сохранять модель в личном кабинете.

curl

curl -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_plane/" \
  -H "X-API-Key: YOUR_API_TOKEN" \
  -F "model_file=@ifc-zakladnaya-detail-mn557-21-06-2026.ifc"

curl (Windows)

curl.exe -X GET "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/health/" -H "X-API-Key: YOUR_API_TOKEN"

curl.exe -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_plane/" ^
  -H "X-API-Key: YOUR_API_TOKEN" ^
  -F "model_file=@ifc-zakladnaya-detail-mn557-21-06-2026.ifc"

python

import requests

url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_plane/"
headers = {
    "X-API-Key": "YOUR_API_TOKEN",
}

with open("ifc-zakladnaya-detail-mn557-21-06-2026.ifc", "rb") as f:
    files = {
        "model_file": (
            "ifc-zakladnaya-detail-mn557-21-06-2026.ifc",
            f,
            "application/octet-stream",
        )
    }
    response = requests.post(url, headers=headers, files=files, timeout=120)

print(response.status_code)
print(response.json())

js

async function createSessionByPlane() {
  const fileInput = document.querySelector("#model-file-input");
  const modelFile = fileInput?.files?.[0];
  if (!modelFile) {
    throw new Error("Выберите IFC-файл в input#model-file-input");
  }

  const formData = new FormData();
  formData.append("model_file", modelFile);

  const response = await fetch("https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_plane/", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_TOKEN",
    },
    body: formData,
  });

  const data = await response.json();
  if (!response.ok) {
    throw new Error(JSON.stringify(data));
  }

  console.log(response.status);
  console.log(data);
}

createSessionByPlane().catch(console.error);

c#

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class GipVisionByPlaneExample
{
    public static async Task Main()
    {
        var apiToken = "YOUR_API_TOKEN";
        var filePath = "ifc-zakladnaya-detail-mn557-21-06-2026.ifc";
        var url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_plane/";

        using var http = new HttpClient();
        using var form = new MultipartFormDataContent();
        using var stream = File.OpenRead(filePath);
        using var fileContent = new StreamContent(stream);

        fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
        form.Add(fileContent, "model_file", Path.GetFileName(filePath));
        http.DefaultRequestHeaders.Add("X-API-Key", apiToken);

        var response = await http.PostAsync(url, form);
        var body = await response.Content.ReadAsStringAsync();

        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(body);
    }
}

Пример успешного ответа (201)

По схеме SessionResponse сервер возвращает: deeplink, expires_at, onetime_code.

{
  "deeplink": "gipvision://session/uuid",
  "expires_at": "2026-02-22T12:30:45Z",
  "onetime_code": "123456"
}

Чтобы реально запустить AR-сессию, ваше приложение должно открыть значение из поля deeplink на устройстве пользователя через системный механизм deep link. Иными словами, API только возвращает ссылку gipvision://..., а открытие ссылки выполняет клиентское приложение (iOS), из которого пользователь запускает сценарий.

Примеры вызова из другого приложения: iOS - openURL

Разместить по двери

Endpoint: POST /api/gip-vision/v1/session/by_scan/
Файл: ifc-kabinet-26-r26-21-02-2026.ifc

Пример сцены для размещения по двери: точка point_1 задает позицию пользователя, точка point_2 - направление взгляда.

Важно по системам координат:

• alignment - обязательный объект выравнивания модели по скану.
• Можно передать один model_file или несколько multipart parts model_files. Поля взаимоисключающие.
• Для model_files допускаются IFC, GLB и USDZ; порядок parts сохраняется в ответе detail.
• Для каждого GLB действует лимит публичного API: максимум 5000 mesh-node элементов.
• Готовые файлы для iOS/AR-клиента нужно брать из detail-поля model_assets: сначала reality_url, затем fallback usdz_url.
• Поддерживаются два взаимоисключающих режима: point_1 + point_2 или corners + wall_normal.
• alignment.corners - 4 точки проёма в порядке [BL, BR, TR, TL], формат [[x, y, z], ...].
• alignment.wall_normal - нормаль стены в формате [x, y, z].
• Для координат из Revit (Z-up) передавайте alignment.coordinate_system=z-up; сервер автоматически нормализует координаты в Y-up.
• Для Y-up (например, из three.js-вьюеров) поле alignment.coordinate_system можно не передавать, по умолчанию используется y-up.
• В multipart-запросе массивы (alignment.point_1, alignment.point_2, alignment.corners, alignment.wall_normal) допускается передавать JSON-строкой.

Режим point_1 + point_2: Z-up (Revit)

curl

curl -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/" \
  -H "X-API-Key: YOUR_API_TOKEN" \
  -F "model_file=@ifc-kabinet-26-r26-21-02-2026.ifc" \
  -F "alignment.point_1=[8.07369, 3.663441, 0.0]" \
  -F "alignment.point_2=[8.050343, 4.092017, 0.0]" \
  -F "alignment.coordinate_system=z-up"

curl (Windows)

curl.exe -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/" ^
  -H "X-API-Key: YOUR_API_TOKEN" ^
  -F "model_file=@ifc-kabinet-26-r26-21-02-2026.ifc" ^
  -F "alignment.point_1=[8.07369, 3.663441, 0.0]" ^
  -F "alignment.point_2=[8.050343, 4.092017, 0.0]" ^
  -F "alignment.coordinate_system=z-up"

python

import requests

url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/"
headers = {
    "X-API-Key": "YOUR_API_TOKEN",
}

data = {
    "alignment.point_1": "[8.07369, 3.663441, 0.0]",
    "alignment.point_2": "[8.050343, 4.092017, 0.0]",
    "alignment.coordinate_system": "z-up",
}

with open("ifc-kabinet-26-r26-21-02-2026.ifc", "rb") as model_f:
    files = {
        "model_file": ("ifc-kabinet-26-r26-21-02-2026.ifc", model_f, "application/octet-stream"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=120)

print(response.status_code)
print(response.json())

js

async function createSessionByScanZUp() {
  const fileInput = document.querySelector("#model-file-input");
  const modelFile = fileInput?.files?.[0];
  if (!modelFile) {
    throw new Error("Выберите IFC-файл в input#model-file-input");
  }

  const formData = new FormData();
  formData.append("model_file", modelFile);
  formData.append("alignment.point_1", "[8.07369, 3.663441, 0.0]");
  formData.append("alignment.point_2", "[8.050343, 4.092017, 0.0]");
  formData.append("alignment.coordinate_system", "z-up");

  const response = await fetch("https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_TOKEN",
    },
    body: formData,
  });

  const data = await response.json();
  if (!response.ok) {
    throw new Error(JSON.stringify(data));
  }

  console.log(response.status);
  console.log(data);
}

createSessionByScanZUp().catch(console.error);

c#

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class GipVisionByDoorZUpExample
{
    public static async Task Main()
    {
        var apiToken = "YOUR_API_TOKEN";
        var modelPath = "ifc-kabinet-26-r26-21-02-2026.ifc";
        var url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/";

        using var http = new HttpClient();
        using var form = new MultipartFormDataContent();
        http.DefaultRequestHeaders.Add("X-API-Key", apiToken);

        var model = new StreamContent(File.OpenRead(modelPath));
        model.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
        form.Add(model, "model_file", Path.GetFileName(modelPath));

        form.Add(new StringContent("[8.07369, 3.663441, 0.0]"), "alignment.point_1");
        form.Add(new StringContent("[8.050343, 4.092017, 0.0]"), "alignment.point_2");
        form.Add(new StringContent("z-up"), "alignment.coordinate_system");

        var response = await http.PostAsync(url, form);
        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(body);
    }
}

Режим point_1 + point_2: Y-up (например, three.js)

curl

curl -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/" \
  -H "X-API-Key: YOUR_API_TOKEN" \
  -F "model_file=@ifc-kabinet-26-r26-21-02-2026.ifc" \
  -F "alignment.point_1=[8.07369, 0.0, -3.663441]" \
  -F "alignment.point_2=[8.050343, 0.0, -4.092017]"

curl (Windows)

curl.exe -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/" ^
  -H "X-API-Key: YOUR_API_TOKEN" ^
  -F "model_file=@ifc-kabinet-26-r26-21-02-2026.ifc" ^
  -F "alignment.point_1=[8.07369, 0.0, -3.663441]" ^
  -F "alignment.point_2=[8.050343, 0.0, -4.092017]"

python

import requests

url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/"
headers = {
    "X-API-Key": "YOUR_API_TOKEN",
}

data = {
    "alignment.point_1": "[8.07369, 0.0, -3.663441]",
    "alignment.point_2": "[8.050343, 0.0, -4.092017]",
}

with open("ifc-kabinet-26-r26-21-02-2026.ifc", "rb") as model_f:
    files = {
        "model_file": ("ifc-kabinet-26-r26-21-02-2026.ifc", model_f, "application/octet-stream"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=120)

print(response.status_code)
print(response.json())

js

async function createSessionByScanYUp() {
  const fileInput = document.querySelector("#model-file-input");
  const modelFile = fileInput?.files?.[0];
  if (!modelFile) {
    throw new Error("Выберите IFC-файл в input#model-file-input");
  }

  const formData = new FormData();
  formData.append("model_file", modelFile);
  formData.append("alignment.point_1", "[8.07369, 0.0, -3.663441]");
  formData.append("alignment.point_2", "[8.050343, 0.0, -4.092017]");

  const response = await fetch("https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_TOKEN",
    },
    body: formData,
  });

  const data = await response.json();
  if (!response.ok) {
    throw new Error(JSON.stringify(data));
  }

  console.log(response.status);
  console.log(data);
}

createSessionByScanYUp().catch(console.error);

c#

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class GipVisionByDoorYUpExample
{
    public static async Task Main()
    {
        var apiToken = "YOUR_API_TOKEN";
        var modelPath = "ifc-kabinet-26-r26-21-02-2026.ifc";
        var url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/";

        using var http = new HttpClient();
        using var form = new MultipartFormDataContent();
        http.DefaultRequestHeaders.Add("X-API-Key", apiToken);

        var model = new StreamContent(File.OpenRead(modelPath));
        model.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
        form.Add(model, "model_file", Path.GetFileName(modelPath));

        form.Add(new StringContent("[8.07369, 0.0, -3.663441]"), "alignment.point_1");
        form.Add(new StringContent("[8.050343, 0.0, -4.092017]"), "alignment.point_2");
        // alignment.coordinate_system опущен: по умолчанию y-up

        var response = await http.PostAsync(url, form);
        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(body);
    }
}

Режим corners + wall_normal (когда известны координаты проёма)

Как составить список [BL, BR, TR, TL]:

• BL (Bottom Left) - нижний левый угол проёма.
• BR (Bottom Right) - нижний правый угол проёма.
• TR (Top Right) - верхний правый угол проёма.
• TL (Top Left) - верхний левый угол проёма.
• Лево/право определяйте, глядя на проём со стороны, куда направлен вектор wall_normal.
• Порядок точек должен идти по контуру без перестановок: BL -> BR -> TR -> TL.

Пример данных проёма:

{
  "corners": [
    [7.510000190734863, -2.220446049250313e-16, -4.145116873249376],
    [8.410000190734863, -2.220446049250313e-16, -4.145116873249376],
    [8.410000190734863, 2.05, -4.145116873249376],
    [7.510000190734863, 2.05, -4.145116873249376]
  ],
  "wall_normal": [0, 0, 1],
}

curl

curl -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/" \
  -H "X-API-Key: YOUR_API_TOKEN" \
  -F "model_file=@ifc-kabinet-26-r26-21-02-2026.ifc" \
  -F "alignment.corners=[[7.510000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, 2.05, -4.145116873249376], [7.510000190734863, 2.05, -4.145116873249376]]" \
  -F "alignment.wall_normal=[0, 0, 1]"

curl (Windows)

curl.exe -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/" ^
  -H "X-API-Key: YOUR_API_TOKEN" ^
  -F "model_file=@ifc-kabinet-26-r26-21-02-2026.ifc" ^
  -F "alignment.corners=[[7.510000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, 2.05, -4.145116873249376], [7.510000190734863, 2.05, -4.145116873249376]]" ^
  -F "alignment.wall_normal=[0, 0, 1]"

python

import requests

url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/"
headers = {
    "X-API-Key": "YOUR_API_TOKEN",
}

data = {
    "alignment.corners": "[[7.510000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, 2.05, -4.145116873249376], [7.510000190734863, 2.05, -4.145116873249376]]",
    "alignment.wall_normal": "[0, 0, 1]",
}

with open("ifc-kabinet-26-r26-21-02-2026.ifc", "rb") as model_f:
    files = {
        "model_file": ("ifc-kabinet-26-r26-21-02-2026.ifc", model_f, "application/octet-stream"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=120)

print(response.status_code)
print(response.json())

js

async function createSessionByScanCorners() {
  const fileInput = document.querySelector("#model-file-input");
  const modelFile = fileInput?.files?.[0];
  if (!modelFile) {
    throw new Error("Выберите IFC-файл в input#model-file-input");
  }

  const formData = new FormData();
  formData.append("model_file", modelFile);
  formData.append(
    "alignment.corners",
    "[[7.510000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, 2.05, -4.145116873249376], [7.510000190734863, 2.05, -4.145116873249376]]",
  );
  formData.append("alignment.wall_normal", "[0, 0, 1]");

  const response = await fetch("https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_TOKEN",
    },
    body: formData,
  });

  const data = await response.json();
  if (!response.ok) {
    throw new Error(JSON.stringify(data));
  }

  console.log(response.status);
  console.log(data);
}

createSessionByScanCorners().catch(console.error);

c#

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class GipVisionByDoorCornersExample
{
    public static async Task Main()
    {
        var apiToken = "YOUR_API_TOKEN";
        var modelPath = "ifc-kabinet-26-r26-21-02-2026.ifc";
        var url = "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_scan/";

        using var http = new HttpClient();
        using var form = new MultipartFormDataContent();
        http.DefaultRequestHeaders.Add("X-API-Key", apiToken);

        var model = new StreamContent(File.OpenRead(modelPath));
        model.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
        form.Add(model, "model_file", Path.GetFileName(modelPath));

        form.Add(new StringContent("[[7.510000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, -2.220446049250313e-16, -4.145116873249376], [8.410000190734863, 2.05, -4.145116873249376], [7.510000190734863, 2.05, -4.145116873249376]]"), "alignment.corners");
        form.Add(new StringContent("[0, 0, 1]"), "alignment.wall_normal");
        // alignment.coordinate_system опущен: входные данные уже в y-up

        var response = await http.PostAsync(url, form);
        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(body);
    }
}

Пример успешного ответа (201)

{
  "deeplink": "gipvision://session/uuid",
  "expires_at": "2026-02-22T12:30:45Z",
  "onetime_code": "123456"
}

Когда координаты проёма известны заранее, используйте режим alignment.corners + alignment.wall_normal вместо автоматически определения проёма на сервере point_1 и point_2. Автоматическое определение проёма построено на алгоритме RANSAK. Качество автоматического определения зависит от геометрии стены и примыкающих элементов

Разместить по virtual anchor

Endpoint-ы:

• POST /api/gip-vision/v1/session/by_virtual_anchor/circle-directional/ - окружность с направлением.
• POST /api/gip-vision/v1/session/by_virtual_anchor/rectangle-short-side/ - прямоугольник по короткой стороне.
• POST /api/gip-vision/v1/session/by_virtual_anchor/corner-directional/ - угол.
• POST /api/gip-vision/v1/session/by_virtual_anchor/segment-directional/ - отрезок с направлением.

Для всех типов действует единый контракт: model_file или несколько model_files, GLB не больше 5000 mesh-node элементов, готовые Reality/USDZ файлы возвращаются в detail через model_assets.

Пример: прямоугольный anchor

curl -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_virtual_anchor/rectangle-short-side/" \
  -H "X-API-Key: YOUR_API_TOKEN" \
  -F "model_file=@model.glb" \
  -F "virtual_anchor.anchor_type=rectangle_short_side" \
  -F "virtual_anchor.center=[0, 1.2, -2]" \
  -F "virtual_anchor.width=0.9" \
  -F "virtual_anchor.height=2.05" \
  -F "virtual_anchor.plane_normal=[0, 0, 1]" \
  -F "virtual_anchor.short_side_direction=[1, 0, 0]"

Пример: segment-directional

curl -X POST "https://api-cpsk-superapp.gip.su/api/gip-vision/v1/session/by_virtual_anchor/segment-directional/" \
  -H "X-API-Key: YOUR_API_TOKEN" \
  -F "model_files=@architecture.glb" \
  -F "model_files=@engineering.ifc" \
  -F "virtual_anchor.anchor_type=segment_directional" \
  -F "virtual_anchor.segment_point_1=[0, 1.0, -2]" \
  -F "virtual_anchor.segment_point_2=[1.2, 1.0, -2]" \
  -F "virtual_anchor.plane_normal=[0, 0, 1]" \
  -F "virtual_anchor.placement_source=model_surface"

Пример detail-фрагмента

{
  "model_assets": [
    {
      "order": 0,
      "source_name": "architecture.glb",
      "preferred_format": "reality",
      "reality_url": "https://.../model.reality",
      "usdz_url": "https://.../model.usdz"
    }
  ]
}