API 文档

密钥与鉴权

所有业务请求使用 HTTPS，并携带以下请求头。一个账号只有一个有效密钥；更换密钥请联系管理员，旧密钥在重置后失效。

Authorization: Bearer <管理员提供的密钥>

请把密钥保存在服务器的环境变量中，供后端调用。不要放进网页 JavaScript、URL、公开代码或日志。账号停用、封禁后无法继续调用。

创建任务

POST /tasks · 有图片时使用 multipart/form-data，纯文本任务也支持 application/json。

每个新任务设置一个 Idempotency-Key 请求头，建议使用 UUID。超时或网络错误后，使用相同编号、相同参数和相同文件重试，避免重复创建和扣费。不同任务必须使用新编号。

cURL：文生图

curl --request POST "https://guotiai3.cc/wp-json/site-api/v1/tasks" \
  --header "Authorization: Bearer $SITE_API_KEY" \
  --header "Idempotency-Key: $TASK_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{"type":"text_to_image","prompt":"雨后山间的木屋，柔和晨光"}'

SITE_API_KEY 填入管理员提供的密钥；TASK_REQUEST_ID 填入本次任务的唯一编号，并保存下来供重试使用。

Python：上传图片创建任务

import os
import uuid
import requests

# 每个业务任务生成一次；发生重试时继续使用原来的 request_id。
request_id = str(uuid.uuid4())
headers = {
    "Authorization": "Bearer " + os.environ["SITE_API_KEY"],
    "Idempotency-Key": request_id,
}
with open("input.jpg", "rb") as image:
    response = requests.post(
        "https://guotiai3.cc/wp-json/site-api/v1/tasks",
        headers=headers,
        data={"type": "image_to_video", "prompt": "云朵缓慢移动，镜头平稳推进"},
        files={"image": ("input.jpg", image, "image/jpeg")},
        timeout=90,
    )
response.raise_for_status()
task_code = response.json()["task_code"]

换衣和姿势调整用于完整着装的普通人物编辑；换脸功能用于已获授权的非色情素材。

受理成功：HTTP 202

{
  "task_code": "2026091209301234567",
  "replayed": false,
  "status_url": "<任务查询地址>"
}

task_code 与站内任务 code 一致，为 19 位字符串，请勿转成数字，以免丢失精度。

replayed: true 表示返回了同一请求已创建的任务，没有再次扣款。幂等记录随消费记录保留，不要复用旧编号发起新任务。

查询任务与下载结果

GET /tasks/{task_code}，携带 API 密钥。建议每 5–10 秒查询一次，收到限流响应后退避重试。

{
  "task_code": "2026091209301234567",
  "status": "succeeded",
  "price": 10,
  "charged_amount": 10,
  "refund_status": "none",
  "message": "",
  "result_url": "<短期有效下载地址>",
  "result_expires_in": 600,
  "result_retention_days": 30
}

状态为 queued（排队）、processing（执行、重试或结算中）、succeeded（成功）或 failed（最终失败且已退款）。refund_status 为 none、pending 或 refunded；pending 时继续查询，等待最终结果。

结果链接有效期 10 分钟，过期后重新查询。下载结果地址时不需要附带 API 密钥，也不要把 API 密钥转发给存储域名。已签发的存储链接在有效期内仍可使用，请妥善保管。

结果保留 30 天，请及时下载。已结束任务的输入素材在 7 天后清理；仍在执行或重试的任务保留素材。删除或过期的结果不会返回下载地址。

查询账户

GET /account，携带 API 密钥。返回余额、当前 API 价格、网站时区与日期、每日消费上限、今日已消费和剩余额度。

{
  "balance": 1000,
  "currency": "金币",
  "date": "YYYY-MM-DD",
  "timezone": "<网站时区>",
  "daily_limit": 500,
  "today_spent": 100,
  "daily_remaining": 400,
  "prices": {"text_to_image:default": 10}
}

以上金额仅为响应示例，实际价格以此接口及下表为准。账户接口不返回个人联系方式等资料。

价格与退款

具体价格请商家与管理员协商，量大优惠更大。下表为当前基础报价，合作价格与计费方式请在开通前确认。

视频换脸按每 30 秒计费，不足 30 秒按 30 秒计算；时长由服务器读取。其余功能按次计费。

使用本站金币余额。任务受理时扣款，排队和执行中的任务计入当日 API 消费；查询任务与账户不收取金币。

最终失败按创建时的价格退回金币，并回退原扣款日期的 API 消费额度。重试中的任务等待最终结果后结算。价格变动不影响已经受理的任务。

每个账号每分钟最多 60 次创建请求、500 次 API 请求。

错误处理

{"code":"invalid_api_key","message":"请提供有效 API 密钥","data":{"status":401}}