生成 API

用于异步图像和视频任务的 APIClaw 生成 API

当产品需要稳定提交图像或视频任务、查询任务状态并上传源素材时，请使用生成 API。

API 概览

基础 URL: https://www.apiclaw.net — 使用已部署的 APIClaw 站点来源，或账户中显示的 server address。
认证: Authorization: Bearer $YOUR_API_KEY — 在控制台创建 API key，并以 Bearer token 形式发送。
响应包裹: { code, message, data } — 成功响应会返回 code、message 和带类型的数据 payload。

API 端点

每个生成工作流都遵循同样的流程：提交任务、查询任务状态，并在模型需要图片输入时上传素材。

POST /v2/images/generations — 提交图像任务. 创建异步图像生成任务。
POST /v2/videos/generations — 提交视频任务. 创建异步视频生成任务。
GET /v2/tasks/{task_id} — 查询任务. 轮询直到任务进入终态。
POST /v2/upload — 上传文件. 上传图像素材，并在生成请求中使用返回的 URL。

步骤 1

提交图像或视频生成任务

向图像或视频生成端点发送 JSON。返回结果会包含 task_id，可用于查询进度。视频模型可根据系列使用文本、图片、视频和 extra 选项。

POST /v2/images/generations POST /v2/videos/generations

字段

字段	类型	必填	说明
`model`	string	必填	从模型目录中选择的模型名称。
`prompt`	string	必填	图像或视频生成任务的文本指令。
`images`	array	可选	用于图生视频、首尾帧或参考工作流的图片 URL。
`videos`	array	可选	用于参考工作流；当所选模型支持时，也可用于实际 base 视频编辑的视频 URL。
`duration`	number	可选	当所选模型提供时长控制时，请求的视频时长。
`extra`	object	可选	可选模型控制项，例如 Kling referType、keep_original_sound、sound 或 mode。

示例

curl https://www.apiclaw.net/v2/videos/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "Put the jewelry from the reference image on the person in the video",
    "videos": ["https://cdn.example.com/source.mp4"],
    "images": ["https://cdn.example.com/ref.png"],
    "duration": 8,
    "resolution": "std",
    "extra": {
      "referType": "base"
    }
  }'

提交请求

{
  "model": "kling/kling-v3-omni",
  "prompt": "Put the jewelry from the reference image on the person in the video",
  "videos": [
    "https://cdn.example.com/source.mp4"
  ],
  "images": [
    "https://cdn.example.com/ref.png"
  ],
  "duration": 8,
  "resolution": "std",
  "extra": {
    "referType": "base"
  }
}

提交响应

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "status": "submitted"
  }
}

注意事项

打开模型详情页，查看该模型可使用的请求参数。
图像和视频生成都是异步任务，即使结果很快生成也是如此。
Kling 源视频编辑请传 videos 和 extra.referType = "base"；普通图片参考只传 images。

步骤 2

查询任务状态直到终态

使用提交返回的 task_id 轮询任务端点。当状态变为 completed、failed、cancelled 或 canceled 时停止轮询。

GET /v2/tasks/{task_id}

字段

字段	类型	必填	说明
`task_id`	string	必填	提交端点返回的任务标识。
`status`	string	必填	任务状态，例如 submitted、processing、completed、failed 或 cancelled。
`progress`	number	可选	当 provider 暴露进度时返回的进度百分比。
`result`	object	可选	任务完成后返回的图像或视频 URL。
`error`	object	可选	任务失败时的 provider 或 gateway 错误详情。

示例

curl https://www.apiclaw.net/v2/tasks/task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y \
  -H "Authorization: Bearer $YOUR_API_KEY"

查询请求

{
  "method": "GET",
  "path": "/v2/tasks/task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y"
}

完成响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "task_id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": "https://cdn.example.com/result.mp4",
          "thumbnail_url": "https://cdn.example.com/cover.jpg"
        }
      ],
      "images": [
        {
          "url": "https://cdn.example.com/result.png"
        }
      ]
    },
    "error": null
  }
}

注意事项

使用指数退避或较短固定间隔，避免不必要的轮询。
将 failed、cancelled 和 canceled 视为终态。

步骤 3

为图像输入工作流上传源素材

在提交图生视频或参考图工作流前上传图像文件。将返回的 URL 用于 image_url 或其他模型专属输入字段。

POST /v2/upload

字段

字段	类型	必填	说明
`file`	File	必填	包含图像文件的 multipart 表单字段。
`url`	string	必填	可公开访问、可传入生成请求的素材 URL。
`cosKey`	string	必填	用于追踪和内部查找的存储 key。
`mimeType`	string	必填	上传文件检测出的 MIME 类型。
`fileSize`	number	必填	上传文件大小，单位为字节。

示例

curl https://www.apiclaw.net/v2/upload \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F "file=@./source.png"

上传请求

{
  "content_type": "multipart/form-data",
  "field": "file"
}

上传响应

{
  "cosKey": "uploads/2026/06/source.png",
  "url": "https://cdn.example.com/source.png",
  "mimeType": "image/png",
  "fileSize": 245760
}

注意事项

浏览器 multipart 上传时不要手动设置 Content-Type；让 FormData 自动设置 boundary。
将上传后的 URL 用在支持图片输入的模型中。

模型参数

生成 API 在不同模型间使用一致的任务流程，但每个模型可用的请求参数不同。上线前请打开模型详情页确认字段、限制和示例。

APIClaw