LINK42 SDK 接入

TypeScript 与 Python 服务端 SDK：模型调用、流式响应、私有素材上传和付费视频任务。

不收费的费用预估

POST/v1/estimates

通过 estimates.create 传入 endpoint（chat/completions、images/generations 或 videos）与该接口的 payload。预估使用当前 Key 的授权和实际折扣，不调用上游、不冻结资金。estimated_micro_usd 是微美元，is_free 表示真正免费而非四舍五入为零。过期时间、上游开通与最终账单仍需分别核对；硬性消费上限应在 API 密钥设置预算。

Pythonpython

quote = client.estimates.create(endpoint='images/generations', payload={'model': 'AUTHORIZED_MODEL', 'prompt': 'A product image', 'size': '2K'})
print(quote['estimated_micro_usd'], quote['is_free'])

安装发布包

API 域名为 https://www.link42.ai。OpenAI 兼容客户端用 /v1，Anthropic 原生客户端用 /anthropic，Gemini REST 用 /gemini；原有未加前缀的原生路径继续可用。以下安装包随站点版本提供，不表示已经发布到 npm 或 PyPI。

运行环境为 Node.js 20+ 或 Python 3.10+。LINK42_API_KEY 只放在服务端环境变量中，不要写进前端。

Node.jsbash

npm install https://www.link42.ai/downloads/sdk/link42-sdk-0.1.6.tgz
export LINK42_API_KEY="YOUR_LINK42_KEY"

Pythonbash

python -m pip install https://www.link42.ai/downloads/sdk/link42-0.1.6-py3-none-any.whl
export LINK42_API_KEY="YOUR_LINK42_KEY"

上传参考图并生成视频

POST/v1/videos

创建视频会按实际用量收费。先保存任务 ID，再等待结果；上传素材本身不会发起生成。模型以实时目录中的已开通型号为准。

TypeScriptjavascript

import Link42 from '@link42/sdk';
const client = new Link42();
const image = await client.assets.uploadFile('./reference.png');
const task = await client.videos.create({
  model: process.env.LINK42_VIDEO_MODEL,
  content: [
    { type: 'text', text: 'Slow camera push in.' },
    { type: 'image_url', role: 'first_frame', image_url: { url: image.reference } }
  ],
  duration: 4, resolution: '480p', generate_audio: false
});
console.log(task.id);
const result = await client.videos.wait(task.id);
console.log(result.stored_url ?? result.provider_url);

Pythonpython

import os
from link42 import Link42
client = Link42()
image = client.assets.upload_file('reference.png')
task = client.videos.create(
    model=os.environ['LINK42_VIDEO_MODEL'],
    content=[
        {'type': 'text', 'text': 'Slow camera push in.'},
        {'type': 'image_url', 'role': 'first_frame', 'image_url': {'url': image['reference']}}
    ], duration=4, resolution='480p', generate_audio=False
)
print(task['id'])
result = client.videos.wait(task['id'])
print(result.get('stored_url') or result.get('provider_url'))

流式调用

POST/v1/chat/completions

TypeScriptjavascript

const stream = await client.chat.completions.create({
  model: process.env.LINK42_TEXT_MODEL,
  messages: [{ role: 'user', content: 'Hello' }], stream: true
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? '');
}

Pythonpython

import os
for chunk in client.chat.completions.create(
    model=os.environ['LINK42_TEXT_MODEL'],
    messages=[{'role': 'user', 'content': 'Hello'}], stream=True
):
    print(chunk['choices'][0].get('delta', {}).get('content', ''), end='', flush=True)

重试与对账

SDK 仅自动重试 GET 请求；付费 POST 和中断的流式请求不会自动重放。等待超时不会取消上游任务，应继续查询同一任务 ID，或显式取消任务。

Link42Error 提供 status、code 和请求编号（TypeScript 为 requestID，Python 为 request_id）。UploadError 保留阶段、upload ID 与 asset ID，确认失败时可以继续调用 complete。

远程 API 地址必须 HTTPS；HTTP 仅允许 localhost、127.0.0.1 和 ::1 本地开发。不跟随重定向。Python SDK 为同步接口，asyncio 应用中请在工作线程调用。

原图与模型转发限制

JPG/PNG/WebP 原图上传默认上限 100 MiB，管理员可设置更小上限。先上传，再使用返回的 asset:// 引用；图片生成及视频直连引用会把原图处理为单张不超过 10 MiB、合计不超过 20 MiB 的模型转发图，存储原图不变。安全解码上限为 4000 万像素；无效或无法安全处理的图片会被拒绝。

外部 URL、内联 data URI 仍遵守所选模型限制；配置供应商素材库的账号按供应商导入限制处理。成功上传素材不代表模型支持该类型的引用。

SDK 支持范围

两个客户端均提供 models.list/get、对话、Responses、Anthropic Messages/Token 统计、JSON 图片生成/编辑、向量、Gemini、图片任务、视频任务、私有素材、用量与评分接口。models.get 使用 models.list 返回的 API 模型 id，不是网页数字 ID。目录按 Key 与组织授权过滤；可见不保证上游此刻可用。

尚未实现 Audio、Realtime、Batch 和 multipart 图片编辑；JSON 图片编辑是参考图编辑。SDK 保留供应商参数字段，但每个模型只能接受其真实支持的能力。

API Key 素材接口

POST/v1/assets

SDK 先预留上传，再向短期存储地址 PUT 文件（不携带 LINK42 Key），最后调用 /v1/assets/uploads/{upload_id}/complete 确认。assets.downloadURL(id) / assets.download_url(id) 返回仅限本人、短期有效的附件链接，不要持久化或公开。服务端检查素材归属、密钥状态和 IP 白名单；不使用浏览器 Cookie。

成本标签与用量 API

GET/v1/usage/report

在控制台为 API Key 设置成本标签，或在单次请求里通过 X-OneRelay-Tags 请求头追加（逗号分隔，最多 10 个、每个不超过 64 字节）。标签不影响路由和价格，只标记用量记录。

开启了“允许读取用量”的 Key 可以读取整个账户的消费：GET /v1/usage/report 按标签、模型、Key 或日期汇总，时间范围最多 93 天（加 format=csv 导出文件）；GET /v1/usage/logs 分页返回调用明细。一个请求带多个标签时会分别计入各标签，合计只计一次。

curlbash

curl https://www.link42.ai/v1/chat/completions \
  -H "Authorization: Bearer $LINK42_API_KEY" \
  -H "X-OneRelay-Tags: project:alpha, env:prod" \
  -H "Content-Type: application/json" \
  -d '{"model": "YOUR_MODEL", "messages": [{"role": "user", "content": "Hello"}]}'

curl "https://www.link42.ai/v1/usage/report?group_by=tag&start=2026-09-01T00:00:00Z&end=2026-09-18T00:00:00Z" \
  -H "Authorization: Bearer $LINK42_API_KEY"

自动路由、路由预设与提示词模板

POST/v1/chat/completions

把 model 设为 auto，由网关在运营方开放的模型中选择：auto 与 auto:quality 优先质量分最高的模型，auto:cost 优先目录价最低的模型，auto:latency 优先近一小时首字延迟最低的模型。只会在 Key 允许调用、且支持该接口的模型中选择。

在控制台 API Key 页保存路由预设，并以 @preset/<slug> 调用：预设中的模型按顺序（或按预设的策略）尝试，某个模型没有可用账号、或上游返回 5xx / 429 时自动换下一个。每个尝试过的模型各有一条用量记录（回退请求的编号以 -fb1、-fb2 … 结尾），按实际模型的价格计费；响应头 X-OneRelay-Model 给出最终应答的模型。设置了偏好供应商时优先（或只）使用这些上游。

在控制台保存的提示词模板，会加在所绑定 Key 发出的对话、Messages、Responses 与 Gemini 请求的系统提示词最前面；为 Key 绑定多个带权重的版本即可做 A/B 测试，并在模板的“版本与效果”中对比。

curlbash

curl -i https://www.link42.ai/v1/chat/completions \
  -H "Authorization: Bearer $LINK42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "@preset/main", "messages": [{"role": "user", "content": "Hello"}]}'

# X-OneRelay-Model: the model that answered

评分与数据集

POST/v1/scores

用本账户任一 API Key 为自己的请求（request_id）或 Claude Code 会话（session_id）打分：name 为 1–40 位小写字母、数字、点、连字符或下划线，value 为 -1000000 到 1000000 的数字，comment 可选；同名再次打分会覆盖。也可以在控制台的会话详情里打分。

控制台可以把请求导出为 JSON Lines 数据集：每行包含用量、请求及所属会话的评分，以及（开启了请求内容捕获时的）请求与响应正文，可按评分名称和最低分值筛选。

curlbash

curl https://www.link42.ai/v1/scores \
  -H "Authorization: Bearer $LINK42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "REQUEST_ID", "name": "helpful", "value": 1, "comment": "correct answer"}'

LINK42 SDK 接入

TypeScript 与 Python 服务端 SDK：模型调用、流式响应、私有素材上传和付费视频任务。

不收费的费用预估

POST/v1/estimates

Pythonpython

quote = client.estimates.create(endpoint='images/generations', payload={'model': 'AUTHORIZED_MODEL', 'prompt': 'A product image', 'size': '2K'})
print(quote['estimated_micro_usd'], quote['is_free'])

安装发布包

运行环境为 Node.js 20+ 或 Python 3.10+。LINK42_API_KEY 只放在服务端环境变量中，不要写进前端。

Node.jsbash

npm install https://www.link42.ai/downloads/sdk/link42-sdk-0.1.6.tgz
export LINK42_API_KEY="YOUR_LINK42_KEY"

Pythonbash

python -m pip install https://www.link42.ai/downloads/sdk/link42-0.1.6-py3-none-any.whl
export LINK42_API_KEY="YOUR_LINK42_KEY"

上传参考图并生成视频

POST/v1/videos

创建视频会按实际用量收费。先保存任务 ID，再等待结果；上传素材本身不会发起生成。模型以实时目录中的已开通型号为准。

TypeScriptjavascript

import Link42 from '@link42/sdk';
const client = new Link42();
const image = await client.assets.uploadFile('./reference.png');
const task = await client.videos.create({
  model: process.env.LINK42_VIDEO_MODEL,
  content: [
    { type: 'text', text: 'Slow camera push in.' },
    { type: 'image_url', role: 'first_frame', image_url: { url: image.reference } }
  ],
  duration: 4, resolution: '480p', generate_audio: false
});
console.log(task.id);
const result = await client.videos.wait(task.id);
console.log(result.stored_url ?? result.provider_url);

Pythonpython

import os
from link42 import Link42
client = Link42()
image = client.assets.upload_file('reference.png')
task = client.videos.create(
    model=os.environ['LINK42_VIDEO_MODEL'],
    content=[
        {'type': 'text', 'text': 'Slow camera push in.'},
        {'type': 'image_url', 'role': 'first_frame', 'image_url': {'url': image['reference']}}
    ], duration=4, resolution='480p', generate_audio=False
)
print(task['id'])
result = client.videos.wait(task['id'])
print(result.get('stored_url') or result.get('provider_url'))

流式调用

POST/v1/chat/completions

TypeScriptjavascript

const stream = await client.chat.completions.create({
  model: process.env.LINK42_TEXT_MODEL,
  messages: [{ role: 'user', content: 'Hello' }], stream: true
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? '');
}

Pythonpython

import os
for chunk in client.chat.completions.create(
    model=os.environ['LINK42_TEXT_MODEL'],
    messages=[{'role': 'user', 'content': 'Hello'}], stream=True
):
    print(chunk['choices'][0].get('delta', {}).get('content', ''), end='', flush=True)

重试与对账

SDK 仅自动重试 GET 请求；付费 POST 和中断的流式请求不会自动重放。等待超时不会取消上游任务，应继续查询同一任务 ID，或显式取消任务。

远程 API 地址必须 HTTPS；HTTP 仅允许 localhost、127.0.0.1 和 ::1 本地开发。不跟随重定向。Python SDK 为同步接口，asyncio 应用中请在工作线程调用。

原图与模型转发限制

外部 URL、内联 data URI 仍遵守所选模型限制；配置供应商素材库的账号按供应商导入限制处理。成功上传素材不代表模型支持该类型的引用。

SDK 支持范围

尚未实现 Audio、Realtime、Batch 和 multipart 图片编辑；JSON 图片编辑是参考图编辑。SDK 保留供应商参数字段，但每个模型只能接受其真实支持的能力。

API Key 素材接口

POST/v1/assets

成本标签与用量 API

GET/v1/usage/report

curlbash

curl https://www.link42.ai/v1/chat/completions \
  -H "Authorization: Bearer $LINK42_API_KEY" \
  -H "X-OneRelay-Tags: project:alpha, env:prod" \
  -H "Content-Type: application/json" \
  -d '{"model": "YOUR_MODEL", "messages": [{"role": "user", "content": "Hello"}]}'

curl "https://www.link42.ai/v1/usage/report?group_by=tag&start=2026-09-01T00:00:00Z&end=2026-09-18T00:00:00Z" \
  -H "Authorization: Bearer $LINK42_API_KEY"

自动路由、路由预设与提示词模板

POST/v1/chat/completions

curlbash

curl -i https://www.link42.ai/v1/chat/completions \
  -H "Authorization: Bearer $LINK42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "@preset/main", "messages": [{"role": "user", "content": "Hello"}]}'

# X-OneRelay-Model: the model that answered

评分与数据集

POST/v1/scores

curlbash

curl https://www.link42.ai/v1/scores \
  -H "Authorization: Bearer $LINK42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "REQUEST_ID", "name": "helpful", "value": 1, "comment": "correct answer"}'