妙图设计 API

主题

快速开始（5 分钟接入指南） ​

本指南帮助你在 5 分钟内完成：创建令牌 → 查询余额 → 提交文生图任务 → 获取结果 → 吊销令牌。

第一步：创建 API 令牌 ​

  1. 登录妙图，进入 账户 → API 密钥 页面。
  2. 点击 创建令牌，填写名称，按需选择权限范围（Scope）。
  3. 复制明文令牌（tsk_live_...），只展示一次，请立即保存。

将令牌保存为环境变量（推荐，避免硬编码到源代码中）：

bash
export TUSEN_API_TOKEN="tsk_live_替换为你的真实令牌"
export TUSEN_API_BASE="https://magiqsight.com/openapi/v1"

安全提示：不要将令牌提交到 Git，不要打印到日志，不要通过 URL 参数传递。

第二步：查询积分余额 ​

确认令牌有效且余额充足：

bash
curl -s \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  "$TUSEN_API_BASE/account/balance"

成功响应示例：

json
{
  "code": 0,
  "msg": "",
  "data": {
    "balance": 850,
    "reserved": 10,
    "available": 840,
    "expiringIn7Days": 0,
    "nextExpireAt": null
  }
}

nextExpireAt 为 Unix 毫秒时间戳，null 表示无即将到期的积分。

  • available：可用积分（balance - reserved）。
  • 若 code 非 0，请参考错误处理。

第三步：提交文生图任务 ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "positive": "a fluffy white cat sitting on a wooden table, natural light",
    "ar": "1:1",
    "count": 1
  }' \
  "$TUSEN_API_BASE/image/text2image"

成功响应示例：

json
{
  "code": 0,
  "msg": "",
  "data": {
    "requestId": "d91d7bc0-7a34-4277-866a-5c3b24baa982",
    "taskId": "img-abc123def456"
  }
}

requestId：若提交时未提供，服务端会自动生成一个 UUID 并返回。

保存 taskId，下一步用它查询结果：

bash
export TASK_ID="img-abc123def456"

每次文生图调用消耗 1 个 API_CALL 积分。

第四步：轮询任务结果 ​

bash
curl -s \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  "$TUSEN_API_BASE/tasks/$TASK_ID"

任务进行中（继续轮询）：

json
{
  "code": 0,
  "msg": "",
  "data": {
    "taskId": "img-abc123def456",
    "taskType": "text2image",
    "status": 0,
    "progress": 0.4,
    "imageUrls": [],
    "imagePreviewUrls": []
  }
}

任务成功（停止轮询）：

json
{
  "code": 0,
  "msg": "",
  "data": {
    "taskId": "img-abc123def456",
    "taskType": "text2image",
    "status": 1,
    "progress": 1.0,
    "imageUrls": ["https://s3.magiqsight.com/private/..."],
    "imagePreviewUrls": ["https://s3.magiqsight.com/private/..."],
    "createTime": 1748736000000,
    "updateTime": 1748736018000
  }
}

状态值说明：

status含义是否终态
4队列等待中否
0处理中否
1成功是
2失败是
3已取消是

推荐轮询间隔：2 秒；5 分钟后仍未完成则停止等待。

Shell 轮询示例（简单循环）：

bash
for i in $(seq 1 150); do
  RESULT=$(curl -s -H "Authorization: Bearer $TUSEN_API_TOKEN" \
    "$TUSEN_API_BASE/tasks/$TASK_ID")
  STATUS=$(echo $RESULT | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
  echo "轮询 $i: status=$STATUS"
  if [ "$STATUS" = "1" ] || [ "$STATUS" = "2" ] || [ "$STATUS" = "3" ]; then
    echo "$RESULT" | python3 -m json.tool
    break
  fi
  sleep 2
done

第五步：吊销令牌（完成测试后） ​

测试完成后，建议在 账户 → API 密钥 页面吊销用于测试的令牌，创建权限最小化的生产令牌。

常见问题 ​

现象可能原因解决方法
code: 1004013000令牌无效或已吊销检查令牌格式，重新创建
code: 1004008000积分余额不足充值积分后重试
code: 1004013001月度积分上限已超提高令牌月度上限或等待下月重置
HTTP 429触发频率限制等待 Retry-After 秒后重试
status: 2（任务失败）输入参数问题或内部错误检查 resultMetadata 字段

下一步 ​

妙图设计 API Beta

Copyright © 2026 MagiqSight