本平台提供 RESTful API 接口，支持通过用户 API Key 免登录方式提交任务、查询任务状态等操作。所有接口均以 JSON 格式返回数据。

复制{
  "error": false,
  "success": true,
  "task_id": "img_task_xxx",
  "status": "queued",
  "message": "任务已提交，正在后台处理..."
}

提交任务和查询任务建议携带个人中心生成的 sk_ API Key。当前接入不需要 API Secret 或签名。

复制X-API-Key: sk_your_api_key_here

复制Authorization: Bearer sk_your_api_key_here

复制POST /backend/api/image_tasks.php?action=generate&api_key=sk_your_api_key_here

根据任务ID查询任务的当前状态和结果。

复制{
  "error": false,
  "task_id": "task_xxx",
  "status": "completed",
  "message": "",
  "result": "https://...",
  "original_result_url": "",
  "created_at": 1719000000,
  "updated_at": 1719000060
}

上传图片、视频、音频等素材，返回的 file_url 可直接作为生图、生视频、人像素材转换等接口的输入 URL。

复制curl -X POST "https://cyimg.cn/backend/api/upload_file.php" \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "file=@/path/to/avatar.png"

复制{
  "error": false,
  "message": "文件上传成功",
  "data": {
    "file_url": "/backend/api/get_file.php?username=USER&filename=upload_xxx.png",
    "file_name": "upload_xxx.png",
    "original_name": "avatar.png",
    "file_size": 123456,
    "file_type": "image/png",
    "is_image": true,
    "thumbnail_created": true,
    "thumbnail_url": "/backend/api/get_file.php?username=USER&filename=upload_xxx.png&thumbnail=true"
  }
}

将已上传的图片 URL 注册到私域人像素材库，生成可在支持素材库的创作流程中复用的人像素材资产。典型流程为：上传文件 → 创建素材组 → 创建素材。

复制curl -X POST "https://cyimg.cn/backend/api/portrait_assets.php" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_group",
    "name": "我的人像素材组",
    "description": "API上传的人像素材"
  }'

复制curl -X POST "https://cyimg.cn/backend/api/portrait_assets.php" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_asset",
    "group_id": "GROUP_ID",
    "name": "主角参考图",
    "url": "https://cyimg.cn/backend/api/get_file.php?username=USER&filename=upload_xxx.png",
    "asset_type": "Image"
  }'

复制curl -X POST "https://cyimg.cn/backend/api/portrait_assets.php" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "list_assets",
    "filter_group_id": "GROUP_ID",
    "page_size": 20
  }'

以下是 cURL / Python / JavaScript 的接入示例：

复制curl -X POST "https://cyimg.cn/backend/api/image_tasks.php?action=generate" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "CONFIG_ID",
    "prompt": "一只可爱的猫咪"
  }'

复制import requests

API_KEY = "sk_your_api_key_here"
BASE = "https://cyimg.cn/backend/api"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 提交任务
resp = requests.post(f"{BASE}/image_tasks.php?action=generate", headers=headers, json={
    "task_id": "CONFIG_ID",
    "prompt": "一只可爱的猫咪"
})
task_id = resp.json()["task_id"]

# 轮询状态
import time
while True:
    r = requests.get(f"{BASE}/image_tasks.php?action=task_status&task_id={task_id}", headers=headers).json()
    if r["status"] in ["completed", "failed"]:
        print(r); break
    time.sleep(5)

复制const res = await fetch('https://cyimg.cn/backend/api/image_tasks.php?action=generate', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk_xxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    task_id: 'CONFIG_ID',
    prompt: '一只可爱的猫咪'
  })
});
const { task_id } = await res.json();