一个地址，接入文本、图片与视频模型

02为什么是 XYtoken

接入一家模型供应商并不复杂。难的是同时接入十家：每家一套 SDK 与 Key，每上一个新模型就要改一次代码，每次故障只能等厂商恢复，账单还散落在不同后台。这些成本不会写在发票上，却会持续发生。

XYtoken 把这些差异收敛到一个接入面，同时保留三件事不变：协议原生、模型可替换、用量可核对。

四条做法

• 协议原生。OpenAI 与 Anthropic 各自保持原生请求与响应格式。迁移通常只需替换 base_url 与模型名，已有 SDK、框架和工具链继续可用。
• 档位可选。同一个模型按官方、混合云、订阅号池、特价分开售卖，价格与稳定性由你选择，平台不会在你不知情时换成更弱的模型。
• 失败明说。参数错误、权限不足、上游异常都返回明确的状态码与错误信息；重试只发生在同一模型的多条供给之间。
• 计量可核对。请求开始预扣、结束按实际用量结算，差额退回；每一笔都能在用量日志里按 request_id 对上。

请求如何流转

请求先到网关：完成鉴权与模型权限校验，按 Key 绑定的质量档位选择供给，转换协议并转发；返回时写入用量与账单。客户端只与网关通信，上游换渠道、加重试，业务代码不需要感知。

03快速开始

先建一把 Key 并选定质量档位，再替换一个地址，就能完成第一次调用。下面的流程以文本模型为例，图片与视频在后续章节展开。

curl https://api.xytoken.com/v1/chat/completions \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      { "role": "system", "content": "你是一位简洁的技术编辑。" },
      { "role": "user", "content": "用三句话说明 API 网关解决了什么问题。" }
    ]
  }'

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["XYTOKEN_API_KEY"],
    base_url="https://api.xytoken.com/v1",
)

completion = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {"role": "system", "content": "你是一位简洁的技术编辑。"},
        {"role": "user", "content": "用三句话说明 API 网关解决了什么问题。"},
    ],
)

print(completion.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XYTOKEN_API_KEY,
  baseURL: "https://api.xytoken.com/v1",
});

const completion = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "system", content: "你是一位简洁的技术编辑。" },
    { role: "user", content: "用三句话说明 API 网关解决了什么问题。" },
  ],
});

console.log(completion.choices[0].message.content);

{
  "id": "chatcmpl-9f3c2a7d",
  "object": "chat.completion",
  "created": 1761643200,
  "model": "deepseek-v4.1-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "API 网关把多家模型的差异收敛成一个入口：你只需要维护一套地址和密钥。它同时负责鉴权、路由、限流与计费，让业务不必为每家供应商写一套适配。换模型时，通常只需要改一个模型名。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 78,
    "total_tokens": 120
  }
}

工具与 SDK 兼容性

只要工具支持自定义 Base URL，通常不需要改业务代码：

04模型质量档位

同一个模型 ID 可以在四个质量档位下售卖。档位不是模型的“能力等级”，而是供给来源、稳定性、速率限制与价格的组合。模型广场会针对每个模型、每个档位分别标价。

价格与稳定性仅为档位之间的相对关系实际可售档位、单价与并发以模型广场为准

在模型广场看价格

打开控制台「模型广场」，搜索模型并进入详情页。「供应渠道」会按官方、混合云、订阅号池、特价分别列出该档位的计费方式、销售倍率与单价；同屏就能比价。不同模型开放的档位不同，价格也不同，选型时把“模型”和“档位”一起看。

创建 Key 时必须选质量

质量写在 Key 上，不写在请求里。新建密钥时选择的档位，决定了这把 Key 后续所有请求走哪一档供给、按哪一档结算；请求体里没有 quality 参数，也无法在单次调用中临时切换。需要换档位，换一把 Key。

{
  "name": "prod-chat",
  "model_quality": "official",      // official | hybrid | subscription | special
  "models": ["deepseek-v4.1-flash", "kimi-k3.1-pro"],
  "quota": 50000000,                // token 或金额上限，按账户设置
  "ip_allowlist": ["203.0.113.24"]
}

按场景选档位

05核心概念

文档里反复出现的几个词，先统一含义：

06模型与端点

接口按能力分组，全部使用同一个域名和同一把 Key。模型 ID 本身不区分档位，档位由 Key 绑定。

查看当前可用模型

不同 Key 看到的模型不同，用模型列表接口确认：

curl https://api.xytoken.com/v1/models \
  -H "Authorization: Bearer $XYTOKEN_API_KEY"

返回的 data[].id 就是请求里应填的模型 ID。价格、上下文长度与参数边界在模型详情页查看；是否可用，还要看你的 Key 是否绑定了该档位、是否勾选了该模型。

07文本模型

文本接口同时提供 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages 三种格式。选你现有 SDK 对应的那套即可；跨协议调用同一个模型也可以，只要模型在对应端点可用。

四款常用模型

下面四款覆盖了从高频轻量到长上下文的常见场景，仅作选型参考，实际可售型号与 ID 以模型广场为准：

模型 ID 大小写与连字符需完全一致，例如 MiniMax-M3.1-Flash 不能写成 minimax-m3.1-flash。

对话补全

最常用的接口是 POST /v1/chat/completions，请求体与响应格式和 OpenAI 一致。下面这段用长上下文模型处理一份长文档：

curl https://api.xytoken.com/v1/chat/completions \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [
      { "role": "system", "content": "你是严谨的研究助理，只依据给定材料回答。" },
      { "role": "user", "content": "把这份 80 页的行业报告整理成 10 条结论，每条不超过 40 字。……" }
    ],
    "temperature": 0.3,
    "max_tokens": 1200
  }'

响应里的 usage 是计费依据：prompt_tokens 按输入价、completion_tokens 按输出价，缓存命中的部分单独列出。

流式输出

把 stream 设为 true，服务端以 SSE 逐块返回，最后发送 data: [DONE]。对延迟敏感的对话，首字时间比完整响应时间更重要。

stream = client.chat.completions.create(
    model="MiniMax-M3.1-Flash",
    messages=[{"role": "user", "content": "写一段 100 字的产品介绍。"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

# 最后一个 chunk 可能只带 usage，用于对账
print()
print("usage:", getattr(chunk, "usage", None))

协议接入

同一把 Key 支持 OpenAI 与 Anthropic 两种原生协议，OpenAI 还提供 Responses 接口。换协议不改变模型能力，只是字段名不同。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["XYTOKEN_API_KEY"],
    base_url="https://api.xytoken.com/v1",
)

resp = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "用一句话解释什么是 API 网关。"}],
)
print(resp.choices[0].message.content)

from anthropic import Anthropic
import os

client = Anthropic(
    api_key=os.environ["XYTOKEN_API_KEY"],
    base_url="https://api.xytoken.com",
)

message = client.messages.create(
    model="kimi-k3.1-pro",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一段产品发布会的开场白。"}],
)
print(message.content[0].text)

curl https://api.xytoken.com/v1/responses \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "input": "用表格对比 TCP 与 UDP 的适用场景。",
    "stream": false
  }'

图片输入

支持视觉的模型可以在 messages 里传图片 URL 或 base64 Data URL：

{
  "model": "kimi-k3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "这张图里有几个按钮？分别是什么？" },
        { "type": "image_url", "image_url": { "url": "https://example.com/ui.png" } }
      ]
    }
  ]
}

图片按输入 token 计费，尺寸越大消耗越高。生产环境先把图片压到业务可接受的分辨率，再做识别。

错误与重试

只对可恢复的错误重试，并且带退避与抖动。盲目重试会把一次小故障放大成一次限流。

import random
import time

RETRYABLE = {408, 409, 429, 500, 502, 503, 504}

def call_with_retry(fn, attempts=3):
    for i in range(attempts):
        try:
            return fn()
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            if status not in RETRYABLE or i == attempts - 1:
                raise
            delay = min(2 ** i, 8) + random.random()
            print(f"retry in {delay:.1f}s after {status}")
            time.sleep(delay)

流式请求如果中途断开，不建议整体自动重试——已输出的内容无法撤回，容易造成重复文本或重复计费。记录断点，让用户手动继续更稳妥。

08图片模型

图片接口是同步的：请求返回时图片已经生成，响应里给出一个 URL 或 base64 数据。生成与编辑都兼容 OpenAI Images 格式，换模型通常只需要改 model。

选型

图片模型之间的差异，主要不在“画得好不好”，而在中文语义、画面内文字、编辑一致性和分辨率上限。先按用途选，再用同一句提示词做小样对比。

以上为当前在售的示例型号，模型 ID 会随版本更新。实际可售型号、价格与参数边界以模型广场与模型详情页为准；图片模型同样按质量档位分别定价。

生成图片

用 POST /v1/images/generations 文生图。下面的请求生成一张 2K 方形海报底图：

curl https://api.xytoken.com/v1/images/generations \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "极简香水广告海报：磨砂玻璃瓶置于浅灰石台，左上冷白侧光，米白渐变背景，右上角留白用于标题，商业摄影质感",
    "size": "2048x2048",
    "n": 1,
    "response_format": "url",
    "watermark": false
  }'

image = client.images.generate(
    model="doubao-seedream-5-0-pro-260628",
    prompt="极简香水广告海报：磨砂玻璃瓶置于浅灰石台，左上冷白侧光，米白渐变背景，右上角留白用于标题，商业摄影质感",
    size="2048x2048",
    n=1,
    response_format="url",
    extra_body={"watermark": False},
)

print(image.data[0].url)

成功时返回图片数组：

{
  "created": 1761643200,
  "data": [
    {
      "url": "https://files.xytoken.com/images/2026/10/9f3c2a7d.webp",
      "revised_prompt": "极简香水广告海报，磨砂玻璃瓶置于浅灰石台……"
    }
  ]
}

换模型只需要改 model。画面里要出现准确的中文文案时，换用 Qwen-Image 3.0 Pro，把标题、副标题用引号单独写出来：

curl https://api.xytoken.com/v1/images/generations \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "prompt": "竖版中文海报：暖米色背景，中央一只白色陶瓷咖啡杯，杯口有热气，主标题“深秋暖饮”，副标题“10 月 30 日上新”，宋体，居中排版",
    "size": "1024x1536",
    "n": 1
  }'

编辑图片

编辑接口使用 multipart/form-data，可以传参考图、蒙版与提示词。常见用途：换背景、改材质、局部重绘、扩图、风格迁移。需要更严格的指令遵循、一次改多处时，把 model 换成 gpt-image-2.5-flare。

curl https://api.xytoken.com/v1/images/edits \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@./product.png" \
  -F "mask=@./mask.png" \
  -F "prompt=把背景替换成浅灰色影棚背景，保留产品、投影和右侧文字" \
  -F "size=1024x1024" \
  -F "n=1"

• image：要编辑的图片，支持 PNG / JPEG / WebP；部分模型支持多张参考图。
• mask：可选。蒙版的透明区域表示允许修改的范围；不传时由模型根据提示词判断。
• prompt：明确写“改什么”和“保留什么”，比只写风格词有效得多。
• 尺寸、格式与文件大小上限随模型不同，超出时返回 400，并给出具体限制。

参数、尺寸与成本

尺寸怎么选：先确认模型支持的档位，再按投放位置选比例。方形适合社媒与商品主图，横版适合 banner，竖版适合开屏与海报。不要用超出模型能力的尺寸让上游裁切，那会白白多付像素钱。

具体单价以模型详情页为准，同一模型在官方、混合云等档位下价格不同。做批量任务前，先用 1 张低分辨率样片确认效果，再按最终尺寸跑量。

提示词建议

图像模型对“具体”的敏感度远高于“华丽”。把模糊描述拆成可执行的视觉要素，效果会稳定很多：

• 结构：主体 → 场景 → 构图/机位 → 光线 → 材质 → 风格。顺序稳定，模型更容易抓住重点。
• 文字：需要画面内文字时，把文案用引号单独写出，并尽量短；中文长句容易糊。
• 反向词：多数模型不支持 negative_prompt，直接描述“要什么”，比依赖“不要什么”更有效。
• 迭代：一次只改一个变量（构图、光线或风格），否则无法判断是哪句话起了作用。

图片常见问题

09视频模型

视频生成是异步任务：先提交，拿到任务 ID，再查询状态，完成后下载。一次生成通常需要几十秒到几分钟，不要在 HTTP 连接里一直等。

失败任务会进入 failed，返回错误原因并自动释放预扣额度，不计费。

提交文生视频任务

用 POST /v1/videos 提交。下面的例子生成一段 10 秒、1080p、16:9 的横版视频：

curl https://api.xytoken.com/v1/videos \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "清晨的薄雾中，一列老式火车穿过山谷，镜头从高处缓慢俯冲，电影感，暖色调",
    "seconds": "10",
    "metadata": {
      "resolution": "1080p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false,
      "seed": 42
    }
  }'

创建成功后立即返回任务对象，不会等待视频生成完成：

{
  "id": "task_9f3c2a7d",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "progress": 0,
  "created_at": 1761643200
}

时长不是统一值：Seedance 2.5 接受 4–30 秒，Seedance 2.0 接受 4–15 秒，Wan 3.0 接受 2–30 秒，MiniMax H3 接受 4–15 秒；填 -1 时由模型决定默认时长，Wan 3.0 不支持 -1。超出范围会在提交时返回 400，而不是生成到一半才失败。

图生视频与首尾帧

单图首帧：把图片放进 images，模型以它为第一帧生成后续画面。

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "让画面中的女孩缓缓转头，微风吹动头发，背景保持静止",
  "images": ["https://cdn.example.com/first-frame.png"],
  "seconds": "5",
  "metadata": { "resolution": "1080p", "ratio": "adaptive" }
}

首尾帧：需要明确图片角色时，改用 metadata.content。一旦传了 content，它会整组替换 images 拼出的素材数组。

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "从首帧自然过渡到尾帧，镜头缓慢推近，光线逐渐变暖",
  "seconds": "-1",
  "metadata": {
    "resolution": "1080p",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "https://cdn.example.com/first.png" },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://cdn.example.com/last.png" },
        "role": "last_frame"
      }
    ]
  }
}

参考视频与音频

支持多模态参考的模型（当前为 Seedance 2.5），可以把视频、音频和图片一起放进 metadata.content，用于模仿运镜、节奏、音色或人物形象：

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "参考视频的运镜与色调，让画面中的舞者在雨夜街头起舞，节奏与背景音乐一致",
  "seconds": "8",
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9",
    "omni_reference_task_type": "reference",
    "content": [
      { "type": "video_url", "video_url": { "url": "https://cdn.example.com/reference.mp4" } },
      { "type": "audio_url", "audio_url": { "url": "https://cdn.example.com/bgm.mp3" } },
      { "type": "image_url", "image_url": { "url": "https://cdn.example.com/actor.png" } }
    ]
  }
}

• 素材必须是公网可访问的 HTTPS URL，或图片的 base64 Data URL。内网地址、带鉴权的链接、file:// 都不行。
• 每类媒体（图 / 视频 / 音频）各自最多 128 个，超出返回 400。
• 含视频输入的任务通常按不同单价档计费，提交前先确认价格。
• 参考素材不是越多越好。选 1–3 个最关键的参考，模型更容易抓住重点。

查询任务与下载

用创建时返回的 id 轮询：

curl https://api.xytoken.com/v1/videos/task_9f3c2a7d \
  -H "Authorization: Bearer $XYTOKEN_API_KEY"

{
  "id": "task_9f3c2a7d",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "completed",
  "progress": 100,
  "created_at": 1761643200,
  "completed_at": 1761643268,
  "metadata": {
    "url": "https://files.xytoken.com/videos/2026/10/9f3c2a7d.mp4"
  }
}

推荐 5 秒起步、逐步退避、设置总超时。下面的脚本同时演示提交、轮询与落盘：

import os
import time
import requests

BASE = "https://api.xytoken.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['XYTOKEN_API_KEY']}"}

created = requests.post(
    f"{BASE}/videos",
    headers=HEADERS,
    json={
        "model": "doubao-seedance-2-5-260628",
        "prompt": "雨夜的霓虹街头，镜头缓慢推进，电影感",
        "seconds": "5",
        "metadata": {"resolution": "720p", "ratio": "16:9"},
    },
    timeout=60,
).json()

task_id = created["id"]
delay = 5

while True:
    task = requests.get(f"{BASE}/videos/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"], task.get("progress"))
    if task["status"] in ("completed", "failed"):
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 20)

if task["status"] == "completed":
    with requests.get(task["metadata"]["url"], stream=True) as resp:
        resp.raise_for_status()
        with open("output.mp4", "wb") as f:
            for chunk in resp.iter_content(1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
else:
    print("任务失败:", task.get("error"))

也可以让网关代理下载，适合需要统一鉴权或隐藏上游地址的场景：

curl -L https://api.xytoken.com/v1/videos/task_9f3c2a7d/content \
  -H "Authorization: Bearer $XYTOKEN_API_KEY" \
  -o output.mp4

模型差异与限制

下表是当前主推的四款视频模型。换模型前先确认时长、分辨率、比例与素材规则，参数不要跨模型套用。

• 本地文件不能直接用。先把图片/视频/音频上传到对象存储，生成可公开访问的 HTTPS 链接，再提交任务。
• 参数不是通用的。换模型时重新确认时长、分辨率、比例与素材规则；size 在部分模型上只是兼容字段。
• 不要把视频模型塞进聊天接口。视频是任务型 API，统一走 /v1/videos。
• 幂等要自己做。提交前记录业务侧的任务请求标识；网络超时后先查任务日志，不要直接重复提交。

计费与失败处理

Seedance 2.x 按输出分辨率与时长折算 token：提交时按“预估输出 token”预扣，完成后按实际用量结算，多退少补。分辨率与是否包含视频输入会影响单价档；ratio: "adaptive" 会按该分辨率下的最大像素面积预扣。

Wan 3.0 按次计费，MiniMax H3 按输出秒数与分辨率计价。无论哪种方式，失败任务都会自动释放预扣额度，不产生费用。

写视频提示词

一条提示词只讲一个镜头。把下面四件事写清楚，结果会稳定很多：

• 主体与动作：谁在做什么。动作要单一、可执行，避免“然后……接着……”的多段叙事。
• 场景与光线：地点、时间、光源方向。逆光、侧光、阴天会直接改变画面质感。
• 镜头运动：推、拉、摇、移、跟，选一个主运动；固定机位也是有效选择。
• 风格与节奏：写实、动画、胶片或广告感；快慢决定观众的情绪节奏。

10计费与额度

XYtoken 按实际用量计费：文本按 token，图片按张或输出 token，视频按秒折算或按次。没有固定席位费，不用不花钱；所有价格在模型广场按质量档位公示。

一次请求如何扣费

1. 请求开始：按当前 Key 档位的价格预扣一笔额度，防止并发请求把余额透支。
2. 请求结束：按实际 token、张数或时长结算，多扣的部分退回额度。
3. 失败或超时：不产生费用；平台在内部换供给重试，也不会重复收费。
4. 账单可追溯：每次请求记录模型、档位、用量、单价与金额，可以逐笔核对。

在「用量日志」里能看到每一笔的预扣、结算与退款。对账时以日志中的 request_id 为准，而不是客户端本地时间。

额度与限流

• Key 额度：每把 API Key 可单独设置上限，适合按业务、按环境隔离。
• 账户余额：余额不足时请求被拒绝，不会产生欠费；充值后即时恢复。
• 模型权限：Key 只能调用被授权的模型。无权限返回 403，不会悄悄降级。
• 限流：按 Key、模型或分组配置速率与并发上限。触发时返回 429，并尽量带上 Retry-After。

用量日志里有什么

五个省钱习惯

1. 分级用模：简单请求走 Flash 级模型，难题再升级到 Pro，通常能省一半以上。
2. 选对档位：核心链路用官方或混合云，离线批量用订阅号池或特价，别让核心流量跑在最低价档。
3. 控制输出：设置 max_tokens，要求结构化短输出；输出比输入贵得多。
4. 图片先样片：低分辨率、1 张确认效果，再按最终尺寸跑量。
5. 视频先试片：5 秒 720p 验证镜头与动作，再上 1080p / 4K 与长时长。

11错误码

错误响应统一为 OpenAI 风格，附带 request_id，便于在日志中检索：

{
  "error": {
    "message": "当前 API Key 没有访问模型 doubao-seedance-2-5-260628 的权限",
    "type": "permission_denied",
    "code": "model_not_entitled",
    "request_id": "req_8f2c1a90"
  }
}

处理顺序：先看 error.type 判断类别，再看 error.code 决定动作，最后把 request_id 记入日志。不要只按 HTTP 状态码分支——不同上游在同一状态码下的语义可能不同。

12常见问题