TUNC.AI / Документація Tunc Art

Як ділитися файлами й відкривати їх у Tunc Art

Кожен файл має коротке приватне посилання, наприклад tuncart.com/Q7m4Kp. Посилання — це адреса, а не ключ.

Потрібні готові налаштування? Приклади містять підказки, які ви вставляєте своєму агентові.

Як відкрити файл

  • Увійдіть через свій акаунт Tunc. Ви можете відкривати власні файли й файли, якими з вами поділилися через робочий простір.
  • Зображення, відео, аудіо, PDF і вебсторінки (у пісочниці, тож скрипти ніколи не запускаються) відкриваються просто на сторінці; Markdown відкривається як відформатований документ, код і файли JSON показуються з підсвічуванням синтаксису (так само на art.tunchub.com), а інший текст і CSV — як звичайний текст. Для Word, Excel, PowerPoint, архівів та інших файлів показано назву, тип і розмір із кнопкою Download. Вебсторінки відкриваються в пісочниці без доступу до вашого акаунта; PDF показує переглядач вашого браузера.
  • Download завжди повертає початкові байти.

Доступ за паролем

Власник може ввімкнути пароль для доступу на сторінці файлу й надіслати його окремо. Будь-хто з посиланням і паролем може відкривати файл щоразу на 30 хвилин. Вимкнення доступу одразу завершує всі розблоковані сеанси. Пароль діє щонайбільше 7 днів або доки не спливе термін файлу; щоб продовжити, задайте його знову. Увімкнути доступ може лише власник: асистент цього зробити не може. Доступ за паролем ніколи не змінює того, що можуть робити агенти власника.

Агенти й API Art

Агенти входять через Tunc із claude.ai, ChatGPT та інших MCP-клієнтів, підключаються за кодом, якщо не мають браузера, або використовують API-ключ. У Tunc Hub Art уже вбудований; дізнайтеся, як це працює.

Вхід через Tunc

MCP-клієнти, що підтримують вхід, підключаються до https://mcp.tuncart.com/mcp через ваш акаунт Tunc: копіювати ключ не потрібно. (Інший продукт доступний на https://mcp.tuncorb.com/mcp.) Ваш клієнт відкриває Tunc; ви входите або створюєте безкоштовний акаунт зі своєю організацією та Умовами, а потім один раз дозволяєте доступ і вибираєте, що клієнтові дозволено.

КлієнтКроки
claude.ai, Claude Desktop and Claude mobileCustomize → Connectors → Add custom connector → назва Tunc Art, URL https://mcp.tuncart.com/mcp → Add → Connect. Безкоштовний план дозволяє один власний конектор; у Team і Enterprise його додає Owner у Organization settings → Connectors. Це посилання відкриває діалог із уже заповненими назвою та URL:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Art&connectorUrl=https%3A%2F%2Fmcp.tuncart.com%2Fmcp
Claude CodeДодайте сервер, потім запустіть /mcp, виберіть tunc-art і Authenticate.
claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp
ChatGPTSettings → Apps & Connectors → Advanced → увімкніть Developer mode → Create → назва Tunc Art, URL https://mcp.tuncart.com/mcp, Authentication OAuth → Create → Connect.
CursorДодайте його до ~/.cursor/mcp.json, потім Settings → MCP: зʼявиться «Needs login» → Login.
{
  "mcpServers": {
    "tunc-art": {
      "url": "https://mcp.tuncart.com/mcp"
    }
  }
}
VS Code (Copilot)Command Palette → MCP: Add Server → HTTP → https://mcp.tuncart.com/mcp → назва tunc-art → дозвольте запит на вхід.
Gemini CLIДодайте його до settings.json, потім запустіть /mcp auth tunc-art.
{
  "mcpServers": {
    "tunc-art": {
      "httpUrl": "https://mcp.tuncart.com/mcp"
    }
  }
}
Copilot StudioTools → Add a tool → New tool → Model Context Protocol → у полі URL вкажіть https://mcp.tuncart.com/mcp → в Authentication виберіть OAuth 2.0, Dynamic discovery.

Клієнт, який приймає лише заголовок, використовує натомість API-ключ.

Агенти без браузера

Агент на сервері чи в терміналі показує вам код і посилання на кшталт https://tuncart.com/connect?code=BCDF-GHJK. Відкрийте його, увійдіть, переконайтеся, що код збігається, і дозвольте доступ. Це вміє будь-яка бібліотека OAuth, що підтримує device grant (RFC 8628):

# Один раз для кожного агента: зареєструйте його (переспрямування не потрібне)
curl -s https://core.tunc.ai/oauth/register -H 'content-type: application/json' \
  -d '{"client_name":"report-writer","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"]}'
# → {"client_id":"dcr_…",…}

# Запросіть код і покажіть людині verification_uri_complete
curl -s https://core.tunc.ai/oauth/device_authorization -d client_id=dcr_… -d scope="orb.read art.read art.write" -d resource=https://mcp.tuncart.com/mcp
# → {"device_code":"…","user_code":"BCDF-GHJK",
#    "verification_uri_complete":"https://tuncart.com/connect?code=BCDF-GHJK","interval":5,"expires_in":600}

# Опитуйте кожні interval секунд, доки людина не дозволить
curl -s https://core.tunc.ai/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=… -d client_id=dcr_…
# → {"error":"authorization_pending"} до того часу, а після дозволу:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}

# Перш ніж токен доступу спливе, обміняйте токен оновлення на нові
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…

Надсилайте токен доступу як Authorization: Bearer до https://mcp.tuncart.com/mcp. Кожне оновлення повертає новий токен оновлення: зберігайте лише найновіший, бо повторне надсилання вже використаного відключає агента.

A2A

Агенти, що підтримують A2A 1.0, знаходять Tunc Art за адресою https://tuncart.com/.well-known/agent-card.json і викликають https://a2a.tuncart.com. Кожне повідомлення містить одну частину data з skill (назвою MCP-інструмента, наприклад art_read) і його arguments; відповідь — це результат інструмента. Використовуйте API-ключ або увійдіть із ресурсом https://a2a.tuncart.com.

curl -s https://a2a.tuncart.com -H "Authorization: Bearer $TUNC_API_KEY" -H 'A2A-Version: 1.0' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{
        "messageId":"m-1","role":"ROLE_USER",
        "parts":[{"data":{"skill":"art_read","arguments":{"operation":"list"}},"mediaType":"application/json"}]}}}'
# → {"jsonrpc":"2.0","id":1,"result":{"message":{"role":"ROLE_AGENT",
#      "parts":[{"data":{…результат інструмента…},"mediaType":"application/json"}],…}}}

Перейменування, зміна доступу чи відключення

Кожен агент і ключ показано на сторінці tunchub.com → Agents & keys, разом із тим, як він підключився і що йому дозволено. Перейменуйте його, скористайтеся Change access, щоб забрати доступ (за більшим агент знову звернеться до вас), або Disconnect: він перестане працювати протягом хвилини. Усі ваші агенти користуються вашою полицею Personal.

Що роблять інструменти

  • art_write: зберігає файл будь-якого типу розміром до 250 MiB. Невеликі файли надсилаються в самому запиті (text або content_base64, до 8 MiB); більші використовують mode: "begin", щоб отримати URL для завантаження, потім PUT із байтами, а тоді mode: "complete". Результат містить artifact_id файлу і його приватне посилання. Файли ніколи не перезаписуються: нова версія — це новий файл.
  • art_read: list знаходить файли, спочатку найновіші, і приймає title, mime_prefix, kind (image, pdf, workbook, presentation, document та інші), created_after, created_before і sort (newest, oldest, name, largest). get з include_content повертає вміст: текст — як текст; PNG, JPEG, GIF або WebP — як зображення; PDF — як зображення сторінок, по чотири за раз (pages визначає, які саме); файли Word, PowerPoint, OpenDocument, iWork і листи — як текст; таблицю — як текст за sheet і range; архів — як список елементів, які читають по одному через part; велике фото — як зменшене зображення. Усе інше розміром до 8 MiB повертається як content_base64, а offset і length читають частину файлу будь-якого розміру.
  • art_delete: видаляє файл, який ви завантажили. Його посилання одразу перестає працювати, пароль для доступу вимикається, і скасувати це неможливо.

Використання API-ключа

Створіть API-ключ на tunchub.com через свій акаунт Tunc. Виберіть, що йому дозволено: читати Tunc Orb (кожен ключ), зберігати й видаляти в Tunc Orb, а також відкривати, завантажувати й видаляти файли Tunc Art. Ключ показується один раз; зберігайте його в сховищі секретів своєї системи, ніколи в підказці. Відключити його можна будь-коли в розділі Agents & keys, і він перестане працювати протягом хвилини.

Один ключ працює з обома API: https://api.tuncorb.com для Tunc Orb і https://api.tuncart.com для Tunc Art. Надсилайте його як Authorization: Bearer <key>.

Підключіть MCP-клієнт

Інструменти Tunc Orb доступні на https://mcp.tuncorb.com/mcp, а Tunc Art — на https://mcp.tuncart.com/mcp. Додайте потрібний, указавши свій ключ у заголовку Authorization (замініть $TUNC_API_KEY):

Claude Code

claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp --header "Authorization: Bearer $TUNC_API_KEY"

Cursor (mcp.json)

{
  "mcpServers": {
    "tunc-art": {
      "url": "https://mcp.tuncart.com/mcp",
      "headers": {
        "Authorization": "Bearer $TUNC_API_KEY"
      }
    }
  }
}

VS Code (mcp.json)

{
  "servers": {
    "tunc-art": {
      "type": "http",
      "url": "https://mcp.tuncart.com/mcp",
      "headers": {
        "Authorization": "Bearer $TUNC_API_KEY"
      }
    }
  }
}

Gemini CLI (settings.json)

{
  "mcpServers": {
    "tunc-art": {
      "httpUrl": "https://mcp.tuncart.com/mcp",
      "headers": {
        "Authorization": "Bearer $TUNC_API_KEY"
      }
    }
  }
}

OpenAI Responses API (tools)

{
  "type": "mcp",
  "server_label": "tunc-art",
  "server_url": "https://mcp.tuncart.com/mcp",
  "authorization": "$TUNC_API_KEY"
}

Ключ без доступу, потрібного інструменту, отримує помилку інструмента, яка називає цей доступ у missing_scope; відключений ключ отримує 401.

Виклик API напряму

# Files you can open (paged)
curl -s "https://api.tuncart.com/v1/files?limit=20" -H "Authorization: Bearer $TUNC_API_KEY"

# Upload: start, send the bytes to upload.url, then complete
curl -s https://api.tuncart.com/v1/files \
  -H "Authorization: Bearer $TUNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"q4-report.pdf","mime_type":"application/pdf","byte_count":482113}'
# → {"artifact":{"id":"…",…},"upload":{"method":"PUT","url":"…","headers":{…},…}}
curl -s https://api.tuncart.com/v1/files/<id>/complete \
  -H "Authorization: Bearer $TUNC_API_KEY" \
  -H "Content-Type: application/json" -d '{"byte_count":482113}'

# Download, and delete a file your key uploaded
curl -s https://api.tuncart.com/v1/files/<id>/content -H "Authorization: Bearer $TUNC_API_KEY" -o q4-report.pdf
curl -s -X DELETE https://api.tuncart.com/v1/files/<id> -H "Authorization: Bearer $TUNC_API_KEY"
curl -s https://api.tuncorb.com/v1/write \
  -H "Authorization: Bearer $TUNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"create","name":"hello","about":"first record",
       "text":"Hello from my agent","mutation_id":"mut_'"$(openssl rand -hex 13)"'"}'

curl -s https://api.tuncorb.com/v1/read \
  -H "Authorization: Bearer $TUNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"get","name":"hello"}'
import os
import secrets

import requests

headers = {"Authorization": f"Bearer {os.environ['TUNC_API_KEY']}"}

# Tunc Orb: зберегти запис (один mutation_id на зміну; повторно використовуйте його під час повторів)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
    "operation": "create", "name": "hello", "about": "перший запис",
    "text": "Привіт від мого агента", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())

# Tunc Art: показати ваші файли
print(requests.get("https://api.tuncart.com/v1/files", headers=headers).json())

Обмеження

  • Добросовісне використання: 50,000 операцій Tunc Orb на день на безкоштовному плані, 500,000 із платним сховищем. Зараховуються читання, пошук і збереження; видалення й перевірки стану — ні. Лічильник обнуляється опівночі за UTC.
  • На кожного агента щосекунди: 50 читань, 20 збережень, 5 пошуків і 20 інших викликів. Короткі сплески — нормально.
  • Tunc Art: 60 завантажень на хвилину на людину і файли розміром до 250 MiB.
  • Сховище спільне для Tunc Hub, Tunc Orb і Tunc Art; сторінка вашого акаунта показує частку кожного продукту.

Помилки

КодЗначенняПодробиці про сховище
507 storage_limitTunc Orb: ваше сховище Tunc заповнене, тому збереження відхилено, після того як для звільнення місця було видалено ваші найстаріші файли Tunc Art, якщо вони були. Читання й видалення працюють і далі.error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceededTunc Art: файл не вміщується, навіть після видалення ваших найстаріших файлів.quota_bytes, active_bytes, requested_bytes, і storage з тими самими полями, що вище
429 rate_limitedЗабагато викликів. Зачекайте details.retry_after_secs (Orb) або час із заголовка Retry-After (обидва). В Orb details.limit вказує, яке саме обмеження: daily, клас (read, write, search або control) або key_sign_in, коли забагато ключів входять одночасно.—
401 auth_required, not_connectedauth_required: ключ відсутній або недійсний. not_connected: ключ відключено або його термін сплив; створіть новий. Tunc Art відповідає unauthenticated на ключ, який не приймає.—
403 forbiddenКлюч не має цього доступу. missing_scope його називає, наприклад orb.write (Orb: error.details.missing_scope). Створіть ключ із цим доступом.—

Помилки Tunc Orb мають вигляд {"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}}; next_step підказує, що робити. Заповнене сховище ніколи не вирішується повторними спробами: видаліть те, що більше не потрібно, або додайте сховище у своєму акаунті.

API файлів Tunc Core з агентом, який увійшов

Агент, який увійшов або якого ви схвалили за кодом на сторінці підключення вашого акаунта, надсилає свій токен доступу до API файлів Tunc Core:

# Start an upload
curl -s https://core.tunc.ai/api/v1/art/files \
  -H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"display_name":"q4-report.pdf","mime_type":"application/pdf","byte_count":482113}'
# → {"artifact":{…},"upload":{"method":"PUT","url":"…","headers":{…},"expires_in_seconds":…}}

# Send the bytes to upload.url with upload.method and upload.headers, then:
curl -s https://core.tunc.ai/api/v1/art/files/<id>/complete \
  -H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
  -H 'content-type: application/json' -d '{"byte_count":482113}'
# Files you can access (paged; filters: title, mime_prefix, kind, created_after, created_before, sort, cursor, limit)
curl -s "https://core.tunc.ai/api/v1/art/files?limit=20" \
  -H "authorization: Bearer $TUNC_ACCESS_TOKEN"

# One file's metadata, then its bytes (Range supported)
curl -s https://core.tunc.ai/api/v1/art/files/<id> -H "authorization: Bearer $TUNC_ACCESS_TOKEN"
curl -s https://core.tunc.ai/api/v1/art/files/<id>/content -H "authorization: Bearer $TUNC_ACCESS_TOKEN" -o q4-report.pdf

Сховище

Tunc Art і Tunc Orb мають спільний обсяг сховища акаунта. Сторінка сховища вашого акаунта показує загальний обсяг і частку кожного продукту. Кожен файл може мати розмір до 250 MiB; агенти надсилають до 8 MiB у самому запиті через MCP, а більші файли — через попередньо підписане завантаження. Вказуйте для кожного файлу справжній тип медіа, щоб працював попередній перегляд.

Файли, збережені агентами, зберігаються 30 днів на безкоштовному плані й 365 днів із платним сховищем, і для кожного файлу показано дату завершення. Коли сховище заповнене, першими видаляються найстаріші файли, а ваш акаунт показує, що саме видалено.