跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

聊天类 API（LLM）是同步的——一次请求返回完整结果。但图像 / 视频 / 音乐生成都需要数秒到数分钟，走异步任务模式。

​
选哪种结果获取方式？

客户端轮询

创建任务后，定期 GET 任务状态直到完成。简单，适合脚本、CLI、Notebook、测试。

Webhook 回调

提交时传 callback_url，完成后我们 POST 结果给你。节省请求次数，适合生产服务。
两种可以同时用——传了 callback_url 也仍可主动查询任务结果。

​
创建任务

POST 提交后同步返回 200，主体里含 task_id： 
{
  "success": true,
  "task_id": "27a1128f-14b5-440e-a82d-510c81e6fcd4"
}
不同接口同步返回的字段不一样：
  • Midjourney / Suno 等支持「等到出结果再返回」的接口：直接给完整结果（图片 URL 等）
  • Veo / Sora 等重型视频接口：只回一个 task_id，结果稍后通过轮询或 Webhook 拿
具体看每个 API 的 API 参考。

​
客户端轮询

通用模式（以 Midjourney /midjourney/tasks 为例）： 
import time, requests

API = "https://api.xhuoapi.ai/v1"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

# 1. 创建任务
r = requests.post(
    f"{API}/midjourney/imagine",
    headers=headers,
    json={"prompt": "A cat sitting on a table"},
).json()
task_id = r["task_id"]

# 2. 轮询
while True:
    info = requests.post(
        f"{API}/midjourney/tasks",
        headers=headers,
        json={"action": "retrieve", "task_id": task_id},
    ).json()

    # finished_at 字段一旦出现，任务即完成
    if info.get("finished_at"):
        print(info["response"])
        break

    time.sleep(5)
注意：/midjourney/tasks retrieve 返回的是 {id, request, response, created_at, started_at, finished_at, ...} 结构——没有 status 字段。判断「是否完成」请看 finished_at 是否存在，或 response 是否非空。其他服务的任务查询接口字段不完全相同，请参考各自 API 文档。 请合理控制轮询频率，避免触发 too_many_requests（429）。建议带退避，并优先依据具体接口的「典型耗时」估算等待。

​
Webhook 回调

把 callback_url 加到请求 body： 
{
  "prompt": "A cat sitting on a table",
  "callback_url": "https://your-server.com/midjourney/callback"
}
任务完成后，我们把结果 POST 到这个地址。回调主体形如： 成功： 
{
  "success": true,
  "task_id": "...",
  "trace_id": "...",
  "image_url": "...",
  "...": "...（其余业务字段，与同步成功响应一致）"
}
失败： 
{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "error": {
    "code": "...",
    "message": "..."
  }
}

​
Webhook 服务端要求

  • 必须是公网可达的 HTTPS（建议）URL
  • 收到回调请尽快返回 2xx，业务处理放后台
  • 回调当前不带签名头。请：
    • 让 callback_url 包含一段不易猜的 token 路径段
    • 或在服务端用 task_id 比对自己之前创建任务时记下的 ID

​
最小示例（Flask）

from flask import Flask, request

app = Flask(__name__)

# 自己维护的「我提交过的 task_id」集合
my_tasks = set()

@app.post("/midjourney/callback")
def callback():
    payload = request.json
    task_id = payload.get("task_id")

    if task_id not in my_tasks:
        return "", 204  # 不是我的任务，忽略

    if payload.get("success"):
        # 处理成功
        save_image(payload["image_url"])
    else:
        # 处理失败
        log_error(payload.get("error"))

    return "", 200

​
选型对比

维度轮询Webhook
上手简单需要公网 HTTPS endpoint
实时性取决于轮询间隔最快（任务结束即推送）
请求消耗每次轮询都是请求0（只接收回调）
失败恢复客户端崩了重启可继续必须自己处理「错过了回调」
适用场景脚本、本地工具、调试生产服务、批量任务

​
失败处理

不论用哪种方式，都可能拿到失败结果。失败响应的 error.code 与同步错误码一致——见 响应格式。任务失败一般不扣费；具体策略以服务详情页为准。

​
下一步

响应格式

所有错误码与状态码

网关与认证

Token、域名、安全