API 概览

IP-SaaS 面向程序提供的核心能力是：用 API 拿到可用代理，并按需更换。

常见场景：

• 采集 / 自动化：批量提取代理、并发使用、目标站点风控时自动更换
• 出海账号 / 投放：长会话保持（粘性出口），按地区 / 运营商筛选
• TikTok 账号矩阵：每个账号绑定一条独占 IP，长期固定不变

两个关键概念

1) 提取（Extract / Get）

你向平台请求一个可用代理，拿到 host:port + 认证信息 后在你的程序里使用。

提取行为分两类：

• 一次性提取：一次拿 1~N 条 IP，自己管理使用
• 会话提取：带上 session 参数，同一个 session 在有效期内尽量复用同一出口

2) 粘性会话（Sticky Session）

业务希望"在一段时间内尽量不换 IP"时，使用粘性会话：

• 同一个 session key 在有效期内会尽量复用同一出口
• 到期 / 上游失效后自动切换到新的出口
• 适合需要登录态保持、Cookie 持久化、用户行为连续性的业务

"尽量不换"≠"永远不换"。上游 IP 本身可能失效、地区轮换、运营商抖动。粘性是承诺最大努力，不是承诺永久固定。 如果你需要"长期固定不变"，请直接购买静态住宅 ISP 或 TikTok 独占出口，而不是依赖粘性会话。

接口形态约定

不同产品线的具体 Base URL、参数命名可能略有不同——以你购买资源后控制台展示的接入信息为准。下文示例里的 https://api.magiccoreai.com/ip-saas/v1 仅为占位写法，实际接入时请用控制台给的 URL。

通用模式：

GET  /v1/extract            提取代理
POST /v1/rotate             更换出口（带 session_id 或 proxy_id）
GET  /v1/usage              查询用量
GET  /v1/sessions           查询会话状态（若产品支持）

详细字段见 API 端点 与 认证与鉴权。