X2.0 接入现有视频生成工作流的 API 调用与错误处理指南

要把 X2.0 接入现有视频生成工作流，先确认你拿到的接入地址、密钥和模型标识分别对应哪个环境，再按“请求 - 校验 - 重试 - 状态码处理”的顺序落地。视频生成任务通常不是一次请求就能拿到成片，接入时要假设“请求成功≠生成成功”，所以还要把任务轮询一并做进去，否则工作流只能跑通提交这一步。

X2.0 接入的关键不是先写生成逻辑，而是先确定 base_url、access_key、model 三个配置项来自同一套环境。建议先发一条最小请求验证返回结构，再处理网络超时和限流；4xx 按参数或鉴权修，5xx 才重试。边界：不要把临时服务地址写进生产配置，也不要把访问密钥放在前端或日志里。

确认 X2.0 的接入方式与所需凭证

在写调用代码之前，先把三个配置项找齐：base_url 是 X2.0 服务所在环境的根地址，access_key 是开通方给你的访问凭证，model 是在该环境可用的模型标识。这三者必须来自同一个开通渠道；拿 A 环境的 key 去调 B 环境的地址，通常会在鉴权或越权环节直接失败。

配置项建议放到环境变量或独立配置文件中，不要硬编码在代码里。一个最小配置片段：

# config/env.sh 示例
X2_BASE_URL="https://your-x2-endpoint.example.com"
X2_ACCESS_KEY="your-access-key"
X2_MODEL_NAME="x2.0-video"

接入地址和密钥一般从服务商控制台、工单回复或内部开通流程获取；如果拿到的材料里没有明确的接口 Base URL，先补齐资料再动工，不要靠猜路径去探测。

构造首条生成请求并校验响应结构

首条请求的目的不是出片，而是验证链路通不通、参数是否被接受。下面给出一段可替换的 Python requests 骨架，接口路径 /generate 是示例，必须按实际文档替换：

import requests

payload = {
    "model": X2_MODEL_NAME,
    "prompt": "一只猫从窗口跳下，落地后变成雪豹，保持光线一致",
    "input": {
        "image_url": "https://your-storage.example.com/start.png"
    },
    "parameters": {
        "duration": 5,
        "resolution": "1280x720"
    }
}

resp = requests.post(
    f"{X2_BASE_URL}/generate",
    headers={
        "Authorization": f"Bearer {X2_ACCESS_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 60),
)
print(resp.status_code)
print(resp.text)

拿到响应后，先不要急着写业务字段。用 resp.json() 解析 body，确认里面有没有任务 ID、请求 ID 或用于后续轮询的标识；如果只返回成功提示而没有任务标识，这个接口很可能不支持异步任务，后续工作流要按同步结果设计。

data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
    raise ValueError("响应中没有可追踪的任务标识")

如果这一步就报 400 或 422，优先检查 prompt、图片地址、duration 等参数是否满足模型约束，不要先怀疑网络。

处理超时、限流与网络层错误

视频生成的提交请求通常要先上传图片或压缩视频，连接阶段容易超时。建议把超时拆成两段：连接超时 5-10 秒，读取超时 60-120 秒；连接超时短一点可以快速失败，读取超时给足是避免任务在处理过程中被客户端提前掐断。

网络错误（ConnectionError、Timeout）和 5xx 服务端错误都可以做重试，但要控制次数。一个常见的指数退避骨架：

import time
from requests.exceptions import ConnectionError, Timeout

def call_with_retry(request_func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return request_func()
        except (ConnectionError, Timeout) as exc:
            if attempt == max_retries - 1:
                raise exc
            time.sleep(2 ** attempt)

这里用 2 ** attempt 做退避：第一次重试前等 1 秒，第二次等 2 秒。如果 X2.0 接口带有幂等键参数，重试时必须携带同一个幂等键，否则同一段请求可能被重复计费或产生多个任务。限流不归网络层处理，重试代码不要无差别吞掉 429。

根据返回状态码定位业务错误

状态码要分层处理，不要把 4xx 和 5xx 混在一起做同样动作。下表是通用的处理策略，具体字段名需要结合 X2.0 返回体确认：

状态码	常见原因	处理动作
200 / 201 / 202	请求被接受，可能返回任务 ID	保存任务 ID，进入轮询或回调流程
400	参数格式错误、缺少必填字段	查看响应 message/errors 修正后重发
401	access_key 缺失、过期或格式错误	检查密钥和环境配置，重新签发后重试
403	权限不足，不能使用当前模型	核对模型名与授权范围，联系开通方
404	接口路径错误或模型名不存在	以实际文档为准替换路径或模型名
422	业务校验失败，例如分辨率或时长超范围	按 detail 逐项修复，不要重复发送相同请求
429	并发超限、触发限流	读取 Retry-After，等待后重试；降低任务提交频率
5xx	服务端异常或上游处理失败	指数退避重试；持续失败则保留 task_id 和响应 body，进入排查流程

在代码里做一个统一的判定分支，避免每个请求都散落状态码硬编码：

if resp.status_code == 422:
    print("参数需修正:", data.get("detail"))
elif resp.status_code == 401:
    print("重新获取 access_key")
elif resp.status_code == 429:
    retry_after = resp.headers.get("Retry-After", "1")
    print(f"限流，等待 {retry_after} 秒")

任务排队不是错误。如果请求返回 200/201/202 并带任务 ID，后续用轮询状态；只有当轮询接口返回 4xx 或持续 5xx 时，才按表里的策略处理。完成这一步，X2.0 接入工作流的问题边界就清晰了：网络层只负责连得上，业务层才负责生成结果对不对。