首页 > 开发者 API

开发者 API

iP社区（ipshequ.com）开放对外 API，开发者与 AI 智能体可用密钥直接调用「上传素材 / 文字转语音 / 创建对口型视频 / 查询任务」，无需网页操作。所有接口返回的文件地址均为完整 URL，可直接下载。智能体也可直接通过 MCP 端点调用全部能力。

🎁 免费试用无需注册

每个设备/IP 限领一次，赠送 1200 算力（约 3 条测试视频），试用密钥 72 小时有效，试用文案限 50 字。用完或过期后到官网注册购买算力，申请正式密钥即可无限调用。

curl -X POST https://www.ipshequ.com/api/open/trial -H 'Content-Type: application/json' -d '{}'

🔑 鉴权

所有开放接口需在请求头携带密钥：

Authorization: Bearer sk-你的密钥
# 也可使用 x-api-key: sk-你的密钥

正式密钥：注册登录后进入「我的 → API 开放服务」创建，每账户最多 5 个，完整密钥仅创建时返回一次，请妥善保存。

📡 接口详情

POST 上传素材

https://www.ipshequ.com/api/open/upload

上传视频或音频文件，返回可访问的完整 URL；该 URL 可直接作为后续接口的 avatar_video_url / reference_audio_url / audio_url 传入（站内地址走短路，不会重复下载）。

参数：file：视频或音频文件（multipart/form-data，单文件 ≤200MB）

返回：{ success, url }

计费：免费

POST 文字转语音

https://www.ipshequ.com/api/open/audio/tts

将文字合成为语音，可提供声音样本克隆音色；不提供样本则用系统默认声音。支持文件上传与 JSON 传地址两种入参形式。

参数：【multipart】text：必填｜speed：可选 0.5~1.8，默认 1｜reference_audio：可选声音样本文件｜voice_id：可选，复用已克隆音色【application/json】text：必填｜speed：可选｜reference_audio_url：可选，声音样本地址（站内地址或公网直链，≤50MB）｜voice_id：可选

返回：{ success, audio_url, duration, cost, voice_id, balance }

计费：60 算力 / 30秒（按文字预估时长，合成失败全额退还）

POST 创建对口型视频

https://www.ipshequ.com/api/open/video/create

提供形象视频，用文字或驱动音频生成对口型视频（异步任务，返回 task_id）。支持文件上传与 JSON 传地址两种入参形式，两者计费与限制口径完全一致。

参数：【multipart】avatar_video：必填形象视频｜text：文字模式必填｜speed：可选语速｜reference_audio：可选声音样本，不传则自动用形象视频原声｜audio：可选驱动音频，优先级高于 text｜callback_url：可选【application/json】avatar_video_url：必填形象视频地址｜text｜speed｜reference_audio_url｜audio_url｜callback_url（地址可为站内 URL 或公网直链，视频 ≤200MB、音频 ≤50MB）

返回：{ success, task_id, status, cost, balance, poll_hint }

计费：300 算力 / 30秒（按音频时长）

GET 查询视频任务

https://www.ipshequ.com/api/open/video/task/:id

轮询任务状态，完成后返回成片下载地址与缩略图（均为完整域名 URL，可直接下载）。

参数：id：路径参数，任务号

返回：{ success, task_id, status, queue_no, result_url, thumbnail_url, audio_duration, cost, error }

计费：免费

💻 完整调用示例

# 1) 领取免费试用密钥（返回 api_key）
curl -X POST https://www.ipshequ.com/api/open/trial -H 'Content-Type: application/json' -d '{}'

# 2) 用返回的 api_key 创建对口型视频（文字模式）
curl -X POST https://www.ipshequ.com/api/open/video/create -H 'Authorization: Bearer sk-trial-xxx' -F 'avatar_video=@/path/to/avatar.mp4' -F 'text=你好，这是一条测试视频'

# 3) 轮询任务，status=done 后下载 result_url
curl https://www.ipshequ.com/api/open/video/task/612 -H 'Authorization: Bearer sk-trial-xxx'

# 4) 下载成片（result_url 为完整域名地址，可直接下载）
curl -o output.mp4 '<result_url>'

任务状态 status：init(语音合成中) / ready(排队中) / processing(合成中) / done(完成) / failed(失败)。

📬 完成回调（callback_url）

创建任务时传入 callback_url（公网可访问的 http/https 地址），任务完成或失败后会向该地址 POST 一条 JSON 通知，无需轮询。为防伪造，请校验签名头。

POST <callback_url>
Content-Type: application/json; charset=utf-8
X-Ipshequ-Event: lipsync.task.finished
X-Ipshequ-Signature: t=1730000000000,v1=<hmac>

{
  "task_id": 612,
  "status": "done",
  "result_url": "https://www.ipshequ.com/uploads/lipsync/xxx.mp4",
  "audio_duration": 12.4,
  "cost": 300,
  "error": null,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "website": "https://www.ipshequ.com"
}

验签方式：签名原文为 "t=" + 时间戳 + "." + 原始请求体JSON字符串，密钥为你的 API 密钥的 SHA256 值：

hmac = HMAC-SHA256( 签名原文 ,  SHA256("sk-你的密钥") )
# 校验时请比对 X-Ipshequ-Signature 中 v1 的值，并容忍 5 分钟以内的时间偏移以防重放

重试策略：单次投递超时 10 秒；返回非 2xx 或超时则在 30 秒、120 秒后各重试一次，全部失败不影响任务状态，仍可用查询接口取结果。任务失败时 error 为中性提示文案，费用已全额退还。

💰 计费

按算力计费，与网页端一致：文字转语音 60 算力 / 30秒，对口型视频 300 算力 / 30秒，上传与查询免费；合成失败全额退还。注册即送体验算力，试用用完可到官网购买。

🤖 MCP 接入（智能体直接调用）

本服务提供标准 MCP（Model Context Protocol）端点，Claude / Cursor / Qoder / Trae / Windsurf 等客户端可直接添加，在对话里说「帮我做条数字人视频」即可全自动完成。

{
  "mcpServers": {
    "ipshequ": {
      "url": "https://www.ipshequ.com/mcp",
      "headers": { "Authorization": "Bearer sk-你的密钥" }
    }
  }
}

端点：https://www.ipshequ.com/mcp（POST 发 JSON-RPC 2.0，支持批量；GET 返回 405，不提供 SSE 订阅；DELETE 结束会话）

鉴权：initialize 与 tools/list 免鉴权，未配置密钥也能读取完整工具清单；业务工具需 Authorization: Bearer 或 x-api-key

零配置试用：工具 ipshequ_request_trial_key 可直接领取免费试用密钥，智能体无需人工注册即可完成首次交付

工具清单：ipshequ_request_trial_key（领试用密钥）、ipshequ_get_balance（查余额与单价）、ipshequ_text_to_speech（文字转语音/声音克隆）、ipshequ_create_avatar_video（创建数字人对口型视频）、ipshequ_get_video_task（查任务与成片）

支持方法：initialize、notifications/initialized、tools/list、tools/call、ping

# 免鉴权读取工具清单
curl -X POST https://www.ipshequ.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'