Use the API from an AI agent

The Agent Skill for Claude

faceswap-api is an Agent Skill: one SKILL.md file that tells Claude what the API does, how to send the key, how to read a launch's answer, what each error code means and what to do about it. It also tells Claude to say what it is about to launch and wait for a yes, because a launch spends swapz.

It contains instructions only, no code. Claude makes the calls with the tools it already has, and only with a key you give it.

Claude Code

Claude Code loads personal skills from ~/.claude/skills and a repository's skills from .claude/skills in it. Put SKILL.md in a folder named faceswap-api in either place, set FACESWAP_API_KEY, and ask Claude for a swap or for integration code. It loads the skill when the request matches.

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 apps

In the Claude apps, download the zip and upload it where your settings list Skills. The apps load it the same way.

There, the skill is most useful for writing and reviewing integration code. For Claude to call the API itself, code execution needs network access to faceswap.ing, and the key has to reach the sandbox without being typed into the chat.

Any agent: Markdown and OpenAPI

https://faceswap.ing/docs/api.md is the quickstart and the full guide as one Markdown file. Paste the address into any agent or chat, or add it as documentation in your editor. https://faceswap.ing/llms.txt indexes it with the rest of the site.

https://faceswap.ing/api/v1/openapi.json is the OpenAPI 3.1 description of every route and field. Each operation has an operationId (listFaces, listTasks, getTask, launchSwap, listUpscales, getUpscale, launchUpscale), which tools that turn an OpenAPI document into agent tools use as the tool's name.

Cursor and other coding agents

In Cursor, add the Markdown file as documentation (Cursor Settings, Indexing and Docs) and mention it with @Docs, or save SKILL.md as a project rule under .cursor/rules.

Agents that read an AGENTS.md file, such as Codex and GitHub Copilot's coding agent, follow a line pointing at the Markdown file: For the faceswap.ing API, read https://faceswap.ing/docs/api.md.

OpenAI

A custom GPT can import the API as an action: give it https://faceswap.ing/api/v1/openapi.json as the schema, and set authentication to API key, custom header x-api-key.

With the OpenAI Agents SDK, wrap the calls you want the agent to have as function tools. Two are enough for most jobs.

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

LangChain's OpenAPI toolkit builds an agent straight from the document. Wrapping the calls as @tool functions, as in the OpenAI sample, gives you tighter control over what the agent may do.

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")

Keep an agent's spending bounded

Give an agent its own key on a team that holds only what you are willing to let it spend. A key spends from one team's wallet and nothing else, and the balance is the limit.

Revoking the key under Settings, API keys stops the agent at once. The per-key rate limits apply to agents too.