提交异步图片任务

提交任务后接口立即返回 task_id，无需等待图片生成完成。

POST/v1/images/generations/async

提交前请先调用 GET /v1/models，并从当前 Token 返回的模型中选择图片模型。示例中的 YOUR_AVAILABLE_MODEL 是占位符，不代表平台推荐模型。

请求参数

参数	类型	必填	说明
model	string	是	当前 Token 的 /v1/models 返回的图片模型
prompt	string	是	图片描述文本
size	string	否	图片尺寸，例如 1024x1024
quality	string	否	图片质量；具体取值以模型能力为准
n	integer	否	生成数量，默认 1；具体上限以模型能力为准
callback_url	string	否	HTTPS 回调地址。传入后，任务成功或失败时会主动通知；使用前需为当前 Token 生成回调密钥

请求示例

cURL

curl --request POST 'https://revora.vip/v1/images/generations/async' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "YOUR_AVAILABLE_MODEL",
    "prompt": "一只坐在霓虹灯下的白猫，电影感，细节清晰",
    "size": "1024x1024",
    "quality": "standard",
    "n": 1,
    "callback_url": "https://merchant.example.com/webhooks/revora-images"
  }'

JavaScript

const imageModel = 'YOUR_AVAILABLE_MODEL'; // 替换为 /v1/models 返回值
const response = await fetch('https://revora.vip/v1/images/generations/async', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.REVORA_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: imageModel,
    prompt: '一只坐在霓虹灯下的白猫，电影感，细节清晰',
    size: '1024x1024',
    quality: 'standard',
    n: 1,
    callback_url: 'https://merchant.example.com/webhooks/revora-images',
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

image_model = "YOUR_AVAILABLE_MODEL"  # 替换为 /v1/models 返回值
response = requests.post(
    "https://revora.vip/v1/images/generations/async",
    headers={"Authorization": f"Bearer {os.environ['REVORA_API_TOKEN']}"},
    json={
        "model": image_model,
        "prompt": "一只坐在霓虹灯下的白猫，电影感，细节清晰",
        "size": "1024x1024",
        "quality": "standard",
        "n": 1,
        "callback_url": "https://merchant.example.com/webhooks/revora-images",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

成功响应

HTTP 202 Accepted

{
  "success": true,
  "data": {
    "task_id": "img_task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "queued",
    "created_at": 1784019600
  }
}

请持久化保存 data.task_id，随后使用查询接口获取结果。

如果传入 callback_url，仍建议保存 task_id，以便在回调延迟或接收失败时使用查询接口兜底。回调地址必须是公网可访问的 HTTPS 地址，不支持 HTTP、内网地址、URL 用户名密码或重定向。

防止重复提交（可选）

普通调用不需要传入 Idempotency-Key。如果客户端会自动重试，或业务要求一次请求只创建一个任务，可以额外添加唯一请求头：

Idempotency-Key: 67d7fc61-346b-4df1-93c6-a6990bca813e

同一用户使用相同 Key 和相同请求重复提交时会返回原任务；相同 Key 对应不同内容时返回 HTTP 409。

兼容调用

也可以请求 POST /v1/images/generations 并在 JSON 顶层传入 "async": true。两种入口使用相同的任务和计费逻辑；新接入建议使用独立异步接口。