赫柏跨境电商生图API说明文档

任务与计费单位说明

{
  "task_unit": "batch_task",
  "image_unit": "image",
  "billing_unit": "successful_image",
  "max_images_per_task": 8,
  "example": "1 reference image + 8 prompts = 1 task with 8 generated images"
}

1. 基础信息

2. 鉴权方式

所有接口都需要在请求头中携带 API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

3. 提交图片生成任务

接口地址

POST /v1/ecom/batch

完整地址

https://vip.hebokuajing.xyz/v1/ecom/batch

请求参数

比例说明

请求示例

curl -X POST "https://vip.hebokuajing.xyz/v1/ecom/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/product.jpg",
    "model": "gpt-image-2-1k",
    "size": "1024x1024",
    "aspect_ratio": "3:4",
    "prompts": [
      "Use this product image as exact reference. Create a premium ecommerce vertical poster."
    ]
  }'

成功响应示例

{
  "success": true,
  "task_id": "ecom_1783178612_7256b0ad0b",
  "job_id": "ecom_1783178612_7256b0ad0b",
  "status": "queued",
  "total": 1,
  "aspect_ratio": "3:4",
  "message": "任务已进入队列",
  "poll_url": "/v1/ecom/tasks/ecom_1783178612_7256b0ad0b",
  "quota": {
    "enabled": true,
    "level": "vip1",
    "daily_limit / daily_image_limit": 40,
    "used_before": 3,
    "reserved / reserved_images": 1,
    "used_after": 4,
    "remaining / remaining_images": 36
  }
}

4. 查询任务状态

接口地址

GET /v1/ecom/tasks/{task_id}

请求示例

curl "https://vip.hebokuajing.xyz/v1/ecom/tasks/ecom_1783178612_7256b0ad0b" \
  -H "Authorization: Bearer YOUR_API_KEY"

生成中响应示例

{
  "task_id": "ecom_xxx",
  "status": "processing",
  "success_count": 0,
  "failed_count": 0,
  "processing_count": 1,
  "items": [
    {
      "task_id": "item_xxx",
      "status": "processing",
      "retry_count": 0,
      "max_retries": 6,
      "manual_retry_allowed": false
    }
  ]
}

成功响应示例

{
  "task_id": "ecom_xxx",
  "status": "completed",
  "success_count": 1,
  "failed_count": 0,
  "results": [
    {
      "task_id": "item_xxx",
      "status": "success",
      "image_url": "https://image.example.com/result.png",
      "retry_count": 0
    }
  ],
  "quota": {
    "reserved / reserved_images": 1,
    "billable": 1,
    "refunded": 0
  }
}

失败响应示例

{
  "task_id": "ecom_xxx",
  "status": "failed",
  "success_count": 0,
  "failed_count": 1,
  "failed_items": [
    {
      "task_id": "item_xxx",
      "status": "failed",
      "retry_count": 6,
      "max_retries": 6,
      "retryable": true,
      "manual_retry_allowed": true,
      "error_message": "HTTP 500: system error"
    }
  ],
  "quota": {
    "reserved / reserved_images": 1,
    "billable": 0,
    "refunded": 1
  }
}

5. 任务状态说明

6. 轮询频率限制

为避免客户端过于频繁查询任务状态，服务端对轮询做了频率限制。

单个任务最多允许：

• 1 小时内最多查询 200 次。
• 任务超过 1 小时还未结束时，服务端会限制高频查询。

查询太频繁时的响应

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{
  "detail": "Polling too frequently",
  "task_id": "ecom_xxx",
  "status": "processing",
  "min_interval": 5,
  "retry_after": 5
}

7. 失败重试

任务最终失败后，如果失败项里有 manual_retry_allowed: true，客户端可以显示“重新生成”按钮。

重试接口

POST /v1/ecom/tasks/{原始task_id}/retry-items

请求示例

curl -X POST "https://vip.hebokuajing.xyz/v1/ecom/tasks/ecom_xxx/retry-items" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_ids": ["item_xxx"]
  }'

响应示例

{
  "success": true,
  "parent_task_id": "ecom_xxx",
  "retry_task_id": "ecom_retry_xxx",
  "retry_job_id": "ecom_retry_xxx",
  "status": "queued",
  "total_retry_items": 1
}

8. 计费与退款规则

9. 额度查询

查询当前额度

GET /v1/ecom/quota

请求示例

curl "https://vip.hebokuajing.xyz/v1/ecom/quota" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "user_id": "3",
  "quota": {
    "enabled": true,
    "level": "vip1",
    "daily_limit / daily_image_limit": 40,
    "used": 4,
    "remaining / remaining_images": 36
  }
}

10. 客户端 JavaScript 示例

提交任务

async function createImageTask(apiKey, imageUrl, prompt) {
  const res = await fetch("https://vip.hebokuajing.xyz/v1/ecom/batch", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      image_url: imageUrl,
      model: "gpt-image-2-1k",
      size: "1024x1024",
      aspect_ratio: "3:4",
      prompts: [prompt]
    })
  });

  const data = await res.json();

  if (!res.ok) {
    throw new Error(data.detail || "Create task failed");
  }

  return data.task_id;
}

轮询任务

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollTask(apiKey, taskId) {
  const start = Date.now();

  while (true) {
    const res = await fetch(`https://vip.hebokuajing.xyz/v1/ecom/tasks/${taskId}`, {
      headers: {
        "Authorization": `Bearer ${apiKey}`
      }
    });

    if (res.status === 429) {
      let retryAfter = Number(res.headers.get("Retry-After")) || 20;

      try {
        const data = await res.json();
        retryAfter = data.retry_after || retryAfter;
      } catch (e) {}

      await sleep(retryAfter * 1000);
      continue;
    }

    const data = await res.json();

    if (data.status === "completed") {
      return {
        status: "completed",
        images: data.results || [],
        task: data
      };
    }

    if (data.status === "failed") {
      return {
        status: "failed",
        failed_items: data.failed_items || [],
        task: data
      };
    }

    if (data.status === "partial_failed") {
      return {
        status: "partial_failed",
        success_items: (data.results || []).filter(x => x.status === "success"),
        failed_items: data.failed_items || [],
        task: data
      };
    }

    const age = (Date.now() - start) / 1000;

    let delay = 20000;

    if (age <= 30) {
      delay = 5000;
    } else if (age <= 180) {
      delay = 10000;
    } else {
      delay = 20000;
    }

    await sleep(delay);
  }
}

重试失败项

async function retryFailedItems(apiKey, originalTaskId, failedItems) {
  const itemIds = failedItems
    .filter(item => item.manual_retry_allowed)
    .map(item => item.task_id);

  if (itemIds.length === 0) {
    throw new Error("No retryable items");
  }

  const res = await fetch(`https://vip.hebokuajing.xyz/v1/ecom/tasks/${originalTaskId}/retry-items`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      task_ids: itemIds
    })
  });

  const data = await res.json();

  if (!res.ok) {
    throw new Error(data.detail || "Retry failed");
  }

  return data.retry_task_id;
}

11. 常见错误处理