视觉引擎 API

视觉引擎提供图片生成、图片编辑、高清放大和其他 AI 视觉能力。接口采用 OpenAI 风格的 HTTP API，支持常见的 SDK 和开发工具。

接口基础地址
https://你的域名/v1
请将“你的域名”替换为管理员提供的实际地址。

调用前准备

注册并登录视觉引擎账号。
在“API 密钥”页面创建一个密钥。
确认账户余额足够，并查看可用模型。
将密钥保存在服务器环境变量中，不要写入网页前端。

身份认证

所有 API 请求都需要在请求头中携带 Bearer 密钥：

Authorization: Bearer sk-你的API密钥

API 密钥等同于账户通行证。请勿发布到 GitHub、网页源代码、聊天群或截图中。如果密钥泄露，请立即在控制台禁用并重新创建。

模型查询

查询当前账户可使用的模型：

curl https://你的域名/v1/models \
  -H "Authorization: Bearer sk-你的API密钥"

返回示例：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2-2k-async",
      "object": "model",
      "owned_by": "visual-engine"
    }
  ]
}

图片生成

使用图片模型生成图片。模型名称以控制台“模型”页面显示为准。

curl https://你的域名/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的API密钥" \
  -d '{
    "model": "gpt-image-2-2k-async",
    "prompt": "一间采光充足的现代电商摄影棚，白色背景，高清产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

常用参数

参数	说明	示例
`model`	模型名称，必填	`gpt-image-2-2k-async`
`prompt`	图片描述，必填	现代电商摄影棚
`size`	图片尺寸，以控制台支持范围为准	`1024x1024`
`n`	生成数量，通常为 1	`1`

异步任务

部分高清图片模型采用异步方式处理。提交请求后会先返回任务编号，需要根据接口返回的地址查询任务状态。

{
  "id": "task_example_123",
  "status": "queued",
  "message": "任务已提交，请稍后查询"
}

任务状态通常包括：

queued：排队中
processing：生成中
succeeded：生成成功
failed：生成失败

请以实际模型在控制台显示的接口说明为准。

错误处理

状态码	含义	处理建议
`401`	密钥无效或未提供	检查 Authorization 格式和密钥状态
`403`	没有权限使用该模型	检查账户分组和模型权限
`429`	请求过于频繁或余额不足	降低请求频率，检查余额和限额
`500`	服务内部错误	稍后重试，并保存请求时间和错误信息

使用限制

请勿生成违法、侵权、诈骗或其他违规内容。
请勿共享、出售或滥用 API 密钥。
请勿使用自动化程序进行高频请求或攻击服务。
批量任务请控制并发，避免超过账户和上游渠道限制。
上传的图片和文字应确保拥有合法使用权。

常见问题

为什么请求返回 401？

请确认请求头使用了 Authorization: Bearer sk-你的API密钥，并检查密钥是否被禁用或复制不完整。

为什么图片任务一直排队？

可能是上游模型繁忙、并发达到限制或渠道暂时不可用。请查看任务日志，等待一段时间后重试。

扣费后生成失败怎么办？

保存任务编号和失败时间，并联系管理员核查日志。退款规则以平台公告和订单记录为准。

在哪里查看余额和调用记录？

登录视觉引擎后，在“钱包”“使用日志”或“任务日志”页面查看。

联系支持

如果遇到接口错误，请提供：请求时间、模型名称、任务编号、状态码和错误信息。请勿发送 API 密钥、登录密码或完整请求签名。