الوثائق

جميع الأدوات عبر الإنترنت

اربط تطبيقك بفهرس أدوات FaceTooFace.

GET /api/v1/tools
GET /api/v1/tools?category=pdf-tools
GET /api/v1/tools?status=beta
GET /api/v1/tools?executable=true

Get a signed price quote

curl -X POST https://www.facetooface.cn/api/v1/quote \
  -H "Authorization: Bearer ftf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"toolId":"text-013","values":{"text":"Hello API"}}'

Quotes expire after ten minutes and are bound to the account, tool and exact input. No credits are charged for a quote.

Execute an available tool

curl -X POST https://www.facetooface.cn/api/v1/execute/text-013 \
  -H "Authorization: Bearer ftf_live_…" \
  -H "Idempotency-Key: request-unique-001" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"…","values":{"text":"Hello API"}}'

The credits API currently executes 139 tools: 20 text, 30 calculator, 15 date and time, 36 developer, 20 DNS and 18 network tools. The 20 DNS tools and 11 of the 18 network tools are network lookups billed at rate N (2 credits per target); the other 108 tools use rate L (1 credit per started 64 KiB). Browser-only tools (visual editors, device APIs) and the arbitrary-request builder are rejected with EXECUTION_NOT_AVAILABLE; every tool entry in GET /api/v1/tools states its api.executable flag, rate class and price unit. A job reserves the quoted amount, settles actual usage once, and releases the hold when execution fails.

Wallet and usage

curl https://www.facetooface.cn/api/v1/credits?ledger=1 -H "Authorization: Bearer ftf_live_…"
curl "https://www.facetooface.cn/api/v1/usage?limit=50&status=failed" -H "Authorization: Bearer ftf_live_…"

Credits are returned as integers split by source (gift, paid, bonus) with the reserved amount, the current tier and, with ?ledger=1, the immutable credit flow. Usage returns billing metadata only — tool, status, credits, key name and time — never your request values or outputs.

Error responses

{
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

Use the same idempotency key when retrying an uncertain request. A reused key with different quoted input is rejected.

Jobs and billing status

POST /api/v1/jobs is the metered entry point: it takes the same signed quote plus a required Idempotency-Key, reserves the upper bound, runs the tool and settles once. Every current class (L and N) finishes inside the request, so the job comes back succeeded; keep the id and poll GET /api/v1/jobs/{jobId} for state, usage.quoted versus usage.settled, the reconstruction of captured and released credits, the inline result, plus the plan-3.1 envelope fields `engineVersion`, `evidence.method`/`evidence.measuredAt` and `billing.channel`/`billing.rate`/`billing.credits` so a result can be traced to the engine version that produced it — status checks never charge again. A replay with the same key returns the stored job; the same key with other values is refused because the quote is bound to its input. POST /api/v1/jobs/{jobId}/cancel releases everything only while the run is still in flight and answers JOB_ALREADY_FINISHED afterwards. Artifacts are empty for these classes, so GET /api/v1/jobs/{jobId}/artifacts/{artifactId} currently returns ARTIFACT_NOT_FOUND and will serve stored files once the file-based classes open.

curl -X POST https://www.facetooface.cn/api/v1/jobs \
  -H "Authorization: Bearer ftf_live_…" \
  -H "Idempotency-Key: job-unique-0001" \
  -H "Content-Type: application/json" \
  -d '{"toolId":"text-013","quoteToken":"…","values":{"text":"Hello API"}}'

OpenAPI and generated clients

The whole contract is published as OpenAPI 3.1 at /api/v1/openapi.json: the implemented paths, the live rate table, the bearer scheme and every stable error code with its HTTP status. It is public and costs no credits. Generate a typed client with any OpenAPI generator, for example npx openapi-generator-cli generate -i https://www.facetooface.cn/api/v1/openapi.json -g python; this project does not ship a hand-written SDK, and the spec never lists an endpoint that is not implemented.

// JavaScript (Node 18+): quote, then execute
const headers = { Authorization: `Bearer ${process.env.FTF_KEY}`, "Content-Type": "application/json" };
const quote = await (await fetch("https://www.facetooface.cn/api/v1/quote", { method: "POST", headers, body: JSON.stringify({ toolId: "text-013", values: { text: "Hello API" } }) })).json();
const run = await fetch("https://www.facetooface.cn/api/v1/execute/text-013", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ quoteToken: quote.data.quoteToken, values: { text: "Hello API" } })
});
console.log(await run.json());

# Python 3 (requests): wallet ledger and failed calls
import os, requests
headers = {"Authorization": f"Bearer {os.environ['FTF_KEY']}"}
wallet = requests.get("https://www.facetooface.cn/api/v1/credits", params={"ledger": 1}, headers=headers).json()
usage = requests.get("https://www.facetooface.cn/api/v1/usage", params={"limit": 20, "status": "failed"}, headers=headers).json()
print(wallet["data"]["available"], usage["summary"]["errorRate"])