API2CN 异步生图接口指引

异步生图通过“提交即返回、后台排队渲染”彻底规避长请求超时，是支持高分辨率（2K/4K）与高并发大图渲染的高效、稳定性方案。本指引适用于解决批量生图超时与网关报错

API2CN 异步生图接口指引

本文档介绍了如何在使用 智惠API 时，对接 api2cn 提供的异步生图服务。通过异步任务机制，可以有效避免高分辨率或复杂提示词生成过程中的超时问题。

1. 基础配置信息

  • API Base URL: https://api.api2cn.com
  • 默认模型 (Model): gpt-image-2
  • 支持分辨率: 1K / 2K / 4K
  • 存储桶与图片访问:
    • URL 规则: https://s3.api2cn.com/images/{task_id-0}.png
    • 有效时间: 24小时（生成的图片链接在存储桶中仅保留 24 小时，请及时下载或转存）

2. 接口调用与 cURL 示例

2.1 提交任务 (Submit)

向服务器提交异步生图任务。接口会立即返回一个包含 task_id 的响应，代表任务已进入后台队列。

  • 请求方式: POST

  • 请求地址: https://api.api2cn.com/v1/images/generations

  • cURL 示例:

    1
    2
    3
    4
    5
    6
    7
    8
    curl -X POST "https://api.api2cn.com/v1/images/generations" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-image-2",
        "prompt": "A futuristic city with flying cars at sunset, cyberpunk style",
        "size": "2K"
      }'

  • 响应示例:

    1
    2
    3
    4
    5
    6
    7
    8
    {
      "code": 200,
      "message": "Task submitted successfully",
      "data": {
        "task_id": "task_abc123xyz789",
        "status": "processing"
      }
    }

2.2 轮询任务状态 (Polling)

通过上一步获取的 task_id 定期向后端查询生成进度，直至任务状态变为 completed。

  • 请求方式: GET

  • 请求地址: https://api.api2cn.com/v1/tasks/{task_id}

  • cURL 示例:

    1
    2
    curl -X GET "https://api.api2cn.com/v1/tasks/task_abc123xyz789" \
      -H "Authorization: Bearer YOUR_API_KEY"

  • 响应示例 (处理中):

    1
    2
    3
    4
    5
    6
    7
    8
    {
      "code": 200,
      "data": {
        "task_id": "task_abc123xyz789",
        "status": "processing",
        "progress": "50%"
      }
    }

  • 响应示例 (已完成):

    1
    2
    3
    4
    5
    6
    7
    {
      "code": 200,
      "data": {
        "task_id": "task_abc123xyz789",
        "status": "completed"
      }
    }

2.3 获取与下载结果 (Retrieve)

当轮询确认任务完成后，即可根据存储桶规则拼凑链接，直接获取或下载最终生成的图片。

  • 图片 URL 拼凑规则: https://s3.api2cn.com/images/{task_id-0}.png
  • cURL 示例 (下载图片到本地):
    1
    2
    curl -X GET "https://s3.api2cn.com/images/task_abc123xyz789.png" \
      --output generated_image.png

3. 注意事项

  1. 时效性：图片在存储桶中的有效期为 24小时，请务必在此时间内完成转存或下载。
  2. 轮询策略：建议轮询间隔设为 3~5 秒，避免高频请求触发限流。
  3. 分辨率确认：提交任务时请严格对照 1K / 2K / 4K 标准参数填写。