API для ИИ-агентов

Agent Skill для Claude

faceswap-api является Agent Skill, то есть одним файлом SKILL.md. Он объясняет Claude, что делает API, как передавать ключ, как читать ответ на запуск, что означает каждый код ошибки и что с ним делать. Ещё он велит Claude сначала сказать, что именно будет запущено, и дождаться согласия, потому что запуск тратит swapz.

В навыке только инструкции, кода в нём нет. Claude делает вызовы своими инструментами и только с тем ключом, который вы ему дали.

Навык написан на английском. Это инструкции для модели, и Claude выполняет их, даже когда вы пишете ему по-русски.

Claude Code

Claude Code загружает личные навыки из ~/.claude/skills, а навыки репозитория из его папки .claude/skills. Положите SKILL.md в папку faceswap-api в любом из этих мест, задайте FACESWAP_API_KEY и попросите Claude сделать замену или написать код интеграции. Навык загрузится, когда запрос ему подходит.

mkdir -p ~/.claude/skills/faceswap-api
curl -fsSL https://faceswap.ing/docs/api/skill.md -o ~/.claude/skills/faceswap-api/SKILL.md

# The skill reads the key from the environment. Set it where Claude Code runs.
export FACESWAP_API_KEY="fsper_..."

Приложения Claude

В приложениях Claude скачайте zip и загрузите его в настройках, в разделе Skills. Приложения подключают навык так же.

Там навык полезнее всего для того, чтобы писать и проверять код интеграции. Чтобы Claude вызывал API сам, среде выполнения кода нужен сетевой доступ к faceswap.ing, а ключ нужно передать в песочницу, не вводя его в чат.

Любой агент: Markdown и OpenAPI

По адресу https://faceswap.ing/ru/docs/api.md лежат быстрый старт и полное руководство на русском, одним файлом Markdown. То же на английском лежит по адресу https://faceswap.ing/docs/api.md. Вставьте адрес в любого агента или чат или добавьте его как документацию в редакторе. https://faceswap.ing/llms.txt ссылается на оба файла вместе с остальным сайтом.

https://faceswap.ing/api/v1/openapi.json описывает в формате OpenAPI 3.1 каждый маршрут и поле. У каждой операции есть operationId: listFaces, listTasks, getTask, launchSwap, listUpscales, getUpscale или launchUpscale. Инструменты, которые превращают документ OpenAPI в инструменты агента, используют его как имя инструмента.

Cursor и другие агенты для кода

В Cursor добавьте файл Markdown как документацию в Cursor Settings, раздел Indexing and Docs, и упоминайте его через @Docs. Или сохраните SKILL.md как правило проекта в .cursor/rules.

Агенты, которые читают файл AGENTS.md, например Codex и агент GitHub Copilot для кода, следуют строке со ссылкой на файл Markdown: Документация API faceswap.ing: https://faceswap.ing/ru/docs/api.md.

OpenAI

Собственный GPT может подключить API как action. Укажите https://faceswap.ing/api/v1/openapi.json как схему, а в аутентификации выберите API key и custom header x-api-key.

В OpenAI Agents SDK оберните в function tools те вызовы, которые нужны агенту. Для большинства задач хватает двух.

import os

import requests
from agents import Agent, Runner, function_tool

API = "https://faceswap.ing/api/v1"
HEADERS = {"x-api-key": os.environ["FACESWAP_API_KEY"]}


@function_tool
def launch_swap(face_image_url: str, target_urls: list[str]) -> dict:
    """Swap the face in face_image_url onto each target URL. Spends swapz."""
    response = requests.post(
        f"{API}/faceswap/tasks",
        headers=HEADERS,
        json={"faceImageUrl": face_image_url, "targetFiles": [{"url": url} for url in target_urls]},
        timeout=120,
    )
    return response.json()


@function_tool
def get_task(task_id: str) -> dict:
    """Read one task: its status, and each finished file's outputUrl."""
    response = requests.get(f"{API}/faceswap/tasks/{task_id}", headers=HEADERS, timeout=30)
    return response.json()


agent = Agent(
    name="Face swap",
    instructions="Launch face swaps with faceswap.ing and report each outputUrl. Ask before launching.",
    tools=[launch_swap, get_task],
)

result = Runner.run_sync(agent, "Swap https://example.com/face.jpg onto https://example.com/photo.jpg")
print(result.final_output)

LangChain

OpenAPI toolkit из LangChain собирает агента прямо по документу. Если обернуть вызовы в функции @tool, как в примере для OpenAI, вы точнее задаёте, что агенту можно делать.

import os

import requests
from langchain_community.agent_toolkits.openapi import planner
from langchain_community.agent_toolkits.openapi.spec import reduce_openapi_spec
from langchain_community.utilities.requests import RequestsWrapper

spec = reduce_openapi_spec(requests.get("https://faceswap.ing/api/v1/openapi.json", timeout=30).json())
http = RequestsWrapper(headers={"x-api-key": os.environ["FACESWAP_API_KEY"]})

# llm is your chat model. allow_dangerous_requests lets the agent send any
# request the document describes, launches included: use a key on a team
# that holds only what the agent may spend.
agent = planner.create_openapi_agent(spec, http, llm, allow_dangerous_requests=True)
agent.invoke("List my saved faces")

Как ограничить траты агента

Дайте агенту отдельный ключ на команде, где лежит ровно столько, сколько вы готовы позволить ему потратить. Ключ тратит только из кошелька своей команды, и её баланс служит пределом.

Если отозвать ключ в настройках, в разделе «Разработчикам», агент сразу остановится. Лимиты запросов на ключ действуют и для агентов.