Chat, Image & Video API 对话、图像与视频 API

What's available服务内容

You can use these two ways: through our hosted web chat (no code), or by calling the APIs directly from your own code. Every model is available over the API; the hosted chat covers chat, images and video. 您可以通过两种方式使用：通过我们托管的网页聊天界面（无需编写代码），或直接在您自己的代码中调用 API。所有模型均可通过 API 使用；托管聊天界面支持对话、图像与视频生成。

Option 1 — Hosted Web Chat 方式一 — 托管网页聊天 live已上线

The easiest way to try the models together — ask for an image or a short video in a normal chat, and it is generated and appears inline in the conversation. 最简单的体验方式 — 在正常对话中直接要求生成图像或短视频，系统会自动生成并显示在对话中。

Option 2 — Direct API Access方式二 — 直接调用 API

Both endpoints speak the OpenAI API shape your existing client code already knows — integration is normally a base URL + auth header change. 两个接口均采用与 OpenAI API 相同的调用格式，与您现有的客户端代码兼容 — 通常只需更改 base URL 和认证请求头即可完成对接。

Authentication身份认证

Every API request needs two headers, from a Cloudflare Access Service Token issued to your team — request it from your contact rather than reusing another team's token. 每次 API 请求都需要携带两个请求头，其值来自 Cloudflare Access 为您的团队签发的 Service Token — 请向您的对接人申请专属令牌，不要复用其他团队的令牌。

CF-Access-Client-Id: <your-client-id>
CF-Access-Client-Secret: <your-client-secret>

Keep the secret out of shell history and process args — don't pass it as a curl -H command-line argument on a shared machine. Use a curl --config file created with umask 077, or your app's environment/secrets manager. 请勿将密钥暴露在 shell 历史记录或进程参数中 — 在共享机器上不要以 curl -H 命令行参数的形式传递密钥。建议使用 umask 077 创建的 curl --config 配置文件，或使用您应用的环境变量 / 密钥管理服务。

Every curl example on this page uses that config file. Create it once: 本页所有 curl 示例均使用该配置文件。只需创建一次：

umask 077
cat > ~/.cf-access-furniture-comp.curl <<'EOF'
header = "CF-Access-Client-Id: <your-client-id>"
header = "CF-Access-Client-Secret: <your-client-secret>"
EOF
chmod 600 ~/.cf-access-furniture-comp.curl

Each endpoint below is a separate Cloudflare Access application. You may be issued a different token per endpoint — if so, keep one config file per endpoint and point --config at the matching one. 下方每个接口都是独立的 Cloudflare Access 应用。您可能会为每个接口获得不同的令牌 — 若是如此，请为每个接口分别保存配置文件，并在 --config 中指向对应文件。

Chat Completions (Nemotron)对话补全接口（Nemotron） live已上线

Your team's Service Token is provisioned — this endpoint is ready to use. 您团队专属的 Service Token 已开通 — 该接口现已可用。

from openai import OpenAI

client = OpenAI(
    base_url="https://nemotron3-ultra.tfd-runai.com/v1",
    api_key="unused",  # auth is via the CF-Access-* headers below, not a bearer key
    default_headers={
        "CF-Access-Client-Id": "<your-client-id>",
        "CF-Access-Client-Secret": "<your-client-secret>",
    },
)

result = client.chat.completions.create(
    model="nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4",
    messages=[{"role": "user", "content": "Describe a mid-century modern armchair in one paragraph."}],
)
print(result.choices[0].message.content)

Image Generation (Qwen-Image)图像生成接口（Qwen-Image） live已上线

Your team's Service Token is provisioned — this endpoint is ready to use. 您团队专属的 Service Token 已开通 — 该接口现已可用。

Request fields请求参数 — POST /v1/images/generations

curl -s https://qwen-image.tfd-runai.com/v1/images/generations \
  --config ~/.cf-access-furniture-comp.curl \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "A minimalist wooden dining chair, natural oak finish, plain white studio background",
        "size": "1024x1024",
        "n": 1
      }' | jq -r '.data[0].b64_json' | base64 -d > chair.png

curl -s https://qwen-image.tfd-runai.com/v1/images/generations \
  --config ~/.cf-access-furniture-comp.curl \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "极简风格木质餐椅，天然橡木色，纯白影棚背景",
        "size": "1024x1024",
        "n": 1
      }' | jq -r '.data[0].b64_json' | base64 -d > chair.png

Image Editing & Composition (Qwen-Image-Edit)图像编辑与合成接口（Qwen-Image-Edit） live已上线

Send one or more of your own images plus a description of the change. This is the same endpoint for a simple edit ("remove the background") and for compositing several images together — the model is given "Picture 1", "Picture 2" and so on internally, so your prompt can refer to each one. 上传一张或多张您自己的图片，并描述需要的修改。简单编辑（如"移除背景"）与多图合成使用的是同一个接口 — 模型内部会将图片依次标记为"图 1""图 2"，因此您可以在提示词中分别引用它们。

Images are sent as repeated multipart image fields — this endpoint takes form fields, not JSON. 图片以多个 multipart image 字段重复上传 — 该接口接收表单字段，而非 JSON。

curl -s https://qwen-image-edit.tfd-runai.com/v1/images/edits \
  --config ~/.cf-access-furniture-comp.curl \
  -F "image=@armchair.png" \
  -F "image=@living-room.png" \
  -F 'prompt=Place the armchair from the first image into the room from the second image, near the window, matching the room lighting' \
  -F "n=1" | jq -r '.data[0].b64_json' | base64 -d > composite.png

curl -s https://qwen-image-edit.tfd-runai.com/v1/images/edits \
  --config ~/.cf-access-furniture-comp.curl \
  -F "image=@armchair.png" \
  -F "image=@living-room.png" \
  -F 'prompt=将第一张图中的扶手椅放入第二张图的房间内，靠近窗户，光照与房间保持一致' \
  -F "n=1" | jq -r '.data[0].b64_json' | base64 -d > composite.png

• Up to 12 input images per request. The model itself takes at most 4. With 5–12 uploaded images, image 1 is sent as it is and images 2–12 are spread, in order, over the other three pictures, with photos placed side by side only where needed (5 images → [1] [2, 3] [4] [5]; 9 → [1] [2, 3, 4] [5, 6, 7] [8, 9]); a sentence mapping your image numbers onto those pictures is added to the front of your prompt and returned in actual_prompt. A 13th image is rejected with a 400. The request keeps the 4-image limit if any image is sent by URL, a file cannot be read, an image costs more than 40 megapixels to decode (an ordinary JPEG is decoded at reduced scale, so phone photos are fine; a PNG, a WEBP or a progressive JPEG is measured whole), or the endpoint is already packing another request. Combined photos are shrunk, so put the one that matters most first — for one product, one photo still beats four; see the box above. 单次请求最多 12 张输入图片。模型本身最多接收 4 张。上传 5–12 张时，第 1 张原样送出，第 2–12 张按顺序分配到另外 3 张图中，仅在需要时把多张照片并排合成一张（5 张 → [1] [2, 3] [4] [5]；9 张 → [1] [2, 3, 4] [5, 6, 7] [8, 9]），并在提示词前加上一句说明您的图片编号对应哪张图，实际使用的提示词会在 actual_prompt 中返回。第 13 张会返回 400 错误。若有任何图片以 URL 方式传入、有文件无法读取、有图片的解码成本超过 4000 万像素（普通 JPEG 会以缩小尺寸解码，手机照片不受影响；PNG、WEBP 与渐进式 JPEG 按完整尺寸计算），或网关正在为另一个请求合并图片，则仍按 4 张上限处理。被合并的照片会缩小，请把最重要的图片放在第一张 — 针对同一件产品，一张照片的效果仍优于四张，请参阅上方说明。
• n is how many candidate images one request returns, default 1. Because the model re-renders rather than composites, asking for more than one and picking is the intended workflow. Over this public hostname prefer n=2: three candidates measured about 77 seconds with the GPUs to themselves, which leaves no room under the ~100 s edge limit once the cluster is busy. Allow for the full wait in your client timeout, and retry on a 524 rather than rewriting the prompt. n 表示单次请求返回几张候选图，默认为 1。由于模型是重新绘制而非直接贴合，建议一次取多张再从中挑选。透过这个公开主机名请优先使用 n=2：实测三张候选图在 GPU 无竞争时约需 77 秒，一旦集群繁忙就会超过约 100 秒的边缘超时限制。请在客户端超时设置中预留足够时间，并在收到 524 时直接重试，而不是修改提示词。
• size defaults to the first input image's dimensions unless you pass one explicitly. Because that default silently decides the output aspect ratio, prompt extension sets it to 1024x1024 when you have not — pass your own size to keep control of it. 若未显式指定 size，将默认采用第一张输入图片的尺寸。由于这个默认值会悄悄决定输出比例， 在您未指定时，提示词改写会将其设为 1024x1024 — 若想自行控制比例，请显式传入 size。
• prompt_extend is OFF by default on this endpoint — the opposite of the image generation endpoint above, and deliberately so. Your prompt is sent to the edit model exactly as you wrote it. The reason: our rewriter reads your text but does not look at the images you attach, so on a composition task ("put the sofa from image 1 into the room from image 2") it loses the instruction, describes a generic room instead, and invents furniture that was in neither of your photos. We measured it on three attempts and the unrewritten prompt won every time, so we turned it off for you rather than leaving you to discover it. You can still opt in for one request with -F "prompt_extend=true" — worth trying when your prompt is a long specification sheet rather than a "put A into B" instruction. It will become the default here once our rewriter can see your attachments. prompt_extend 在本接口默认为「关闭」 — 与上方的图像生成接口相反，这是刻意的设定。您的提示词会原封不动地送给编辑模型。 原因是：我们的改写模型只读取您的文字，不会查看您上传的图片；因此对于合成类任务 （「把第 1 张图的沙发放进第 2 张图的房间」），它会遗失这个指令、改成描述一个普通房间， 还会自行加入两张原图都没有的家具。我们实测了三次，每一次都是「未改写」的版本比较好， 所以我们直接为您关闭，而不是留给您自己踩到。 您仍然可以针对单次请求选择开启：-F "prompt_extend=true" — 当您的提示词是一份很长的规格表、而不是「把 A 放进 B」这类指令时，值得一试。 等到我们的改写模型能够「看见」您上传的图片之后，本接口才会改为预设开启。
• Only response_format: "b64_json" is supported here — not "file", unlike the generation endpoint above. 此接口仅支持 response_format: "b64_json" — 与上方生成接口不同，不支持 "file"。

Video Generation (Wan 2.2 / Cosmos3)视频生成接口（Wan 2.2 / Cosmos3） live已上线

Two models, one identical API — pick by hostname. Neither is OpenAI-shaped: requests are multipart form fields, and a finished video comes back as raw video/mp4 bytes, not JSON with a b64_json field. 两个模型使用完全相同的接口 — 通过主机名区分。二者均不遵循 OpenAI 格式：请求采用 multipart 表单字段，生成完成的视频以原始 video/mp4 字节返回，而非包含 b64_json 字段的 JSON。

Request fields请求参数 — POST /v1/videos

import time, requests

HOST = "https://wan22-t2v.tfd-runai.com"
HEADERS = {
    "CF-Access-Client-Id": "<your-client-id>",
    "CF-Access-Client-Secret": "<your-client-secret>",
}
form = {                                  # multipart form fields, not JSON
    "prompt": (None, "A walnut lounge chair slowly rotating on a plain studio backdrop"),
    "seconds": (None, "5"),               # never omit this
    "size": (None, "832x480"),
    "num_inference_steps": (None, "12"),
}

job = requests.post(f"{HOST}/v1/videos", files=form, headers=HEADERS, timeout=30).json()
vid = job["id"]

while True:                               # each poll returns in well under a second
    st = requests.get(f"{HOST}/v1/videos/{vid}", headers=HEADERS, timeout=30).json()
    if st["status"] == "completed":
        break
    if st["status"] == "failed":
        raise RuntimeError(st.get("error"))
    time.sleep(10)

r = requests.get(f"{HOST}/v1/videos/{vid}/content", headers=HEADERS, timeout=120)
open("chair.mp4", "wb").write(r.content)

import time, requests

HOST = "https://wan22-t2v.tfd-runai.com"
HEADERS = {
    "CF-Access-Client-Id": "<your-client-id>",
    "CF-Access-Client-Secret": "<your-client-secret>",
}
form = {                                  # 使用 multipart 表单字段，而非 JSON
    "prompt": (None, "胡桃木休闲椅在纯色影棚背景前缓慢旋转"),
    "seconds": (None, "5"),               # 请务必传入该参数
    "size": (None, "832x480"),
    "num_inference_steps": (None, "12"),
}

job = requests.post(f"{HOST}/v1/videos", files=form, headers=HEADERS, timeout=30).json()
vid = job["id"]

while True:                               # 每次轮询均在一秒内返回
    st = requests.get(f"{HOST}/v1/videos/{vid}", headers=HEADERS, timeout=30).json()
    if st["status"] == "completed":
        break
    if st["status"] == "failed":
        raise RuntimeError(st.get("error"))
    time.sleep(10)

r = requests.get(f"{HOST}/v1/videos/{vid}/content", headers=HEADERS, timeout=120)
open("chair.mp4", "wb").write(r.content)

status is one of queued, in_progress, completed, failed. The progress field jumps straight from 0 to 100 on completion, so drive any progress display from elapsed time instead. status 的取值为 queued、in_progress、 completed、failed 之一。progress 字段会在完成时直接从 0 跳到 100，因此进度显示请改用已耗时来估算。

Known limits (test deployment)已知限制（测试阶段）

• No SLA — single-replica GPU serving for evaluation, not scaled for production traffic. 暂无 SLA 保障 — 目前为单副本 GPU 部署，用于评估测试，尚未针对生产流量扩容。
• response_format: "url" is not implemented on the image endpoint — always use b64_json or file. 图像接口未实现 response_format: "url" — 请始终使用 b64_json 或 file。
• Requests without the two CF-Access-* headers get intercepted by Cloudflare Access (a redirect/403), not a model-side error. 缺少两个 CF-Access-* 请求头的请求会被 Cloudflare Access 拦截（返回重定向或 403），而非模型端报错。
• Video: use the job API. /v1/videos/sync holds the connection open for the whole generation and will be cut off at ~100 seconds, after the GPU time is already spent. 视频生成请使用任务式接口。/v1/videos/sync 会在整个生成过程中保持连接，并会在约 100 秒后被中断 — 此时 GPU 算力已经消耗。
• One replica per model, so concurrent requests queue behind each other. Two video requests at once means the second waits for the first — allow for that in your polling timeout. 每个模型仅有一个副本，因此并发请求会排队处理。同时发起两个视频请求时，第二个需等待第一个完成 — 请在轮询超时设置中留出余量。
• Generated videos are returned once and not stored for you — save the bytes when you download them. 生成的视频仅返回一次，我们不会为您留存 — 下载后请自行保存文件。