统一认证，多协议调用

认证

所有接口使用 懂api Key。HTTP 请求通过 Bearer Header 传递，不要把 Key 放进 URL、请求体或客户端日志。

Authorization: Bearer sk-你的令牌

JSON 请求使用 Content-Type: application/json；上传图片的 multipart 请求由 SDK 或 curl -F 自动生成 Content-Type 和 boundary，不要套用 JSON 请求头。

Anthropic Messages 同样接受 Bearer 认证，并额外发送 anthropic-version。

端点路由

实时模型目录

目录直接展示服务端返回的能力、端点类型与可用分组。复制完整模型名，并确认令牌分组包含目标模型。

无需登录的机器可读目录：GET /api/geo/catalog。该目录只返回当前真实可用的模型/分组组合与计算后价格。

按产品读取 GET /api/geo/catalog/{product}；按完整模型 ID 读取 GET /api/geo/models/{model_id}。产品值支持 gpt、claude、gemini、grok、kimi、image、video 和 other。

正在读取实时模型目录...

curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer $DONGAPI_API_KEY"

POST /V1/CHAT/COMPLETIONS

Chat Completions

适合兼容 OpenAI Chat Completions 的 SDK 与客户端。首次接入可先使用非流式请求。

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "回答要简洁。"},
      {"role": "user", "content": "只回复 ok"}
    ],
    "stream": false
  }'

需要 SSE 流式输出时设置 "stream": true，并按事件流逐行消费 data: 数据。

POST /V1/RESPONSES

Responses API

适合 Codex 与使用 OpenAI Responses 协议的工具。模型必须支持该端点类型。

curl http://localhost:3000/v1/responses \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "只回复 ok"
  }'

POST /V1/MESSAGES

Anthropic Messages

供 Claude Code 和 Anthropic SDK 兼容调用。直接请求时使用完整 /v1/messages 路径。

curl http://localhost:3000/v1/messages \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "只回复 ok"}
    ]
  }'

Anthropic 客户端要求 Base URL 时填写 http://localhost:3000，让客户端自行追加 /v1/messages。

POST /V1/IMAGES/GENERATIONS

图像生成

图像任务建议使用 Direct 主机。模型、尺寸和返回格式必须以模型广场当前能力为准。

curl http://localhost:3000/v1/images/generations \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "A clean product photo on a white background",
    "size": "1024x1024",
    "n": 1
  }'

POST /V1/IMAGES/EDITS

图像编辑

使用 Direct 主机，以 multipart 上传原图并描述修改要求。将示例模型占位符 替换为当前账户可用且支持编辑的模型 ID；已观察到 gpt-image-2 与 GPT作图 分组组合调用成功， 使用该模型时需确认 Key 所属分组为 GPT作图。

公开 /v1 接口按 Key 所属分组路由，不在请求体中传 group 切换分组。生图成功或模型目录标记为图像能力， 都不代表所有模型支持图像编辑；JSON 图片 URL、mask、多图及尺寸等支持以具体模型为准。

curl http://localhost:3000/v1/images/edits \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL_ID" \
  -F "prompt=Replace the background while preserving the product" \
  -F "image=@input.png" \
  -F "n=1"

将 input.png 替换为本地图片路径。curl -F 自动生成 multipart/form-data 及 boundary；不要叠加 Content-Type: application/json，也不要手写 boundary。

遇到 400，先检查图片字段、文件、格式和模型参数； 502/503 通常指向服务或上游异常，并不表示图片格式错误。 保留 request ID 和错误信息用于排查，避免不检查原因就循环重试。

ASYNCHRONOUS VIDEO TASKS

视频生成

视频接口先创建任务，再轮询任务状态。不同模型支持的时长、分辨率、参考图与 metadata 不同。

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "A slow camera move through a modern workspace"
  }'

curl http://localhost:3000/v1/videos/task_abc123 \
  -H "Authorization: Bearer $DONGAPI_API_KEY"

{
  "id": "task_abc123",
  "object": "video",
  "status": "completed",
  "progress": 100
}

状态为 completed 后，通过 GET /v1/videos/task_abc123/content 获取文件。轮询建议从 5 秒间隔开始并逐步退避；状态为 failed 时保留任务 ID 和错误字段。

Grok 视频参数

使用已公布 Grok JSON 能力的分组，创建路径仍为 POST /v1/videos，仅接收 JSON；图片请先上传为公网可访问的 HTTP 或 HTTPS 地址。以实时模型目录的 video_profile_by_group 为准。

视频按所选模式及分辨率的基准秒价、提交时长和当前分组倍率计费，参考图片不另收张数费；以实时目录的 billing_mode=video_second、price_unit=second 和 price_variants 为准。模式、分辨率、秒数及单价在提交时冻结，使用日志记录相同报价，后续轮询不会按 Token 或当前新价格重复计费。

Grok 按秒档位沿用平台定价规则：美元标价的数值按 1 USD = 1 CNY 形成基准价，再乘一次分组倍率；官方人民币参考价另按约 1 USD = 7 CNY 展示，仅用于对照。例如某档基准价为每秒 P 元、提交 8 秒、分组倍率 0.6 时，费用为 P × 8 × 0.6 = 4.8P 元；各模式与分辨率的当前秒价见Grok 模型页。

已成功创建并返回任务 ID 的 Grok 任务，若随后明确因内容审核失败，按提交时冻结的本站费用结算，保留已扣费用。参数校验失败和其他错误不按此规则推断收费；费用证据不完整时保留预扣并进入核实。

1.5 无参考图时使用基础模型生成。要使用 1.5 或 1080p，请附带参考图。单张参考图生成时，视频比例跟随参考图；比例选择用于纯文本或多张参考图。支持工作台的 references、reference_image_urls、image_url 兼容输入，懂api 会转换为正确图片字段。参考音频、参考视频、首尾帧、quality、seed 等未公布参数不在该分组合同内。

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "镜头缓慢推进，主体保持一致",
    "duration": 8,
    "resolution": "480p",
    "image": {"url": "/YOUR_PUBLIC_IMAGE_PATH"}
  }'

创建响应使用 懂api 任务 id；查询 GET /v1/videos/{id}，完成后通过 GET /v1/videos/{id}/content 携带同一 API Key 下载。API Key 应保存在服务端，避免写入前端页面。

MiniMax-H3 视频参数

模型 ID 以实时模型目录为准（示例中的占位符替换为 MiniMax-H3 的 ID）。创建路径为 POST /v1/videos（JSON）。下列字段放在顶层或 metadata 里都能识别，两处都填时以顶层为准。

首尾帧不能和参考图、参考视频、参考音频同时使用。图片可以是 https 链接或 base64 data URI；视频和音频只接受公网 https 链接，可以先用 POST /api/aigc/uploads（携带同一 API Key，表单字段 file）上传，取得带签名的地址后再提交。

计费按秒：所选模式（文生、图生、参考生）的 768P 每秒单价 × 时长 × 当前分组倍率，在提交时冻结，创建响应的 seconds 即计费时长；生成失败会退回。

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "红色方块从画面左侧平稳滑到右侧",
    "duration": 6,
    "images": [
      "/YOUR_FIRST_FRAME_PATH",
      "/YOUR_LAST_FRAME_PATH"
    ]
  }'

Seedance 2.5 视频参数与计费

名称带 480p、720p 或 1080p 的 Seedance 2.5 型号按秒计费，分辨率由型号决定；名称带时长（如 -30s）的型号按次计费。模型 ID、可用分组和单价以实时模型目录为准。创建路径为 POST /v1/videos（JSON 或 multipart）；也可以用火山方舟原生格式调用，见下方 火山方舟兼容接口。

参数错误在提交时直接返回 400，响应里的 param 指明出错的字段，例如 {"code":"invalid_request","message":"duration 须为整数秒，收到 4.5 (request id: …)","param":"duration"}，不预扣费。

创建和查询响应里的 seconds 是输出秒数，size 是实际输出尺寸（按方舟官方像素表，如 480p 16:9 为 854x480、720p 9:16 为 720x1280）。

计费与方舟官方一致：每秒单价由分辨率和是否带参考视频决定。

• 不带参考视频（文生、参考图、参考音频）：不含视频单价 × 输出秒数 × 分组倍率。
• 带参考视频：含视频单价 ×（输出秒数 + 参考视频总时长）× 分组倍率。参考视频时长按文件实际时长计，精确到毫秒；合计不足 4 秒按 4 秒计。

例：720p 输出 5 秒，带一个 6 秒参考视频，含视频单价 ¥0.9072/秒、分组倍率 1 时，费用为 0.9072 × (5 + 6) = ¥9.98；同样 5 秒不带参考视频为 1.512 × 5 = ¥7.56。各档当前单价见实时模型目录。

提交时平台只读取参考视频的文件头来获得时长。读不到时直接返回 400，不扣费；参考视频所在服务器需支持 HTTP Range（对象存储和 CDN 一般都支持），本站上传的地址可直接读取。模式、分辨率、输出秒数、参考视频时长和单价在提交时冻结，使用日志可核对；生成失败会退回。

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "参考视频 1 的运镜，镜头缓慢推近桌上的咖啡杯",
    "duration": 5,
    "reference_videos": ["SIGNED_REFERENCE_URL"]
  }'

Seedance 按 token 计费（与火山方舟官方计价一致）

名称不带分辨率的 Seedance 2.x 型号（如 seedance-2-5）按火山方舟官方的 token 价目计费：单价（元 / 百万 tokens）由输出分辨率和输入是否含视频决定，与方舟官方价目一致，再乘分组倍率。可用 POST /v1/video/generations、POST /v1/videos 或下方的火山方舟兼容接口调用；模型 ID、可用分组和当前单价以实时模型目录为准。

计费方式：

• tokens =（输入视频时长 + 输出时长）× 输出宽 × 输出高 × 24 / 1024，即方舟官方公式；费用 = tokens × 单价 ÷ 1,000,000 × 分组倍率。
• 提交时按所请求的分辨率、比例和时长预留：比例为 adaptive（或未指定比例且带首帧图）时按该分辨率最大的画幅；时长为 -1 时按最长时长（2.5 为 30 秒，2.0 为 15 秒）；带参考视频时按文件实测时长，合计不足 4 秒按 4 秒。
• 完成后按任务返回的实际用量（usage.completion_tokens）结算，多预留的部分自动退回，结算金额不超过预留；任务未返回用量时按官方公式估算结算。
• 失败不收费：生成失败（含审核未通过）全额退回。

例：Seedance 2.5、720p、16:9、5 秒、不带参考视频，提交时预留 108,900 tokens × ¥70 / 百万 = ¥7.623（再乘分组倍率）；完成后若返回 100,000 tokens，则按 ¥7.00 结算，退回 ¥0.623。使用日志记录单价、预留 tokens 和结算依据。

素材库（按 token 计费的 Seedance 型号）

先把参考图、参考视频或参考音频存进素材库拿到素材 ID，生成时用 asset://素材ID 代替地址引用。导入一次，反复使用：素材一直可用，每次生成都用同一个素材 ID 引用，直到你删除它。写实真人脸的参考图建议走素材库：直接传地址可能被真人风控拒绝。字段名与火山方舟素材记录一致，鉴权同样是 Authorization: Bearer $DONGAPI_API_KEY。

• 按型号分库：每个型号一个素材库，素材只能给导入时的 model 用（见 Models），两个型号都要用就各导入一次；用错型号返回 400 并提示怎么重新导入，不扣费。调整前导入的素材属于 seedance-2-0-official，seedance-2-5 要用请重新导入。
• 状态：Active 可用；Processing 处理中，本站后台自动刷新，一般一两分钟内变成 Active 或 Failed；Failed 看 FailReason。
• 引用写法：放在原来填地址的位置，如 reference_image_urls、metadata.content 里的 image_url.url / video_url.url / audio_url.url、reference_videos，或火山方舟兼容接口的 content[]。素材类型须与所在字段一致。注意 images 表示首帧和尾帧，不是参考图。
• 存储地址：URL 是本站保存的副本（http://localhost:3000/v1/assets/files/…），长期有效，删除素材后失效；链接即凭证，请勿公开。URL 导入时本站先下载一份再交给模型方，下载不了时直接用原地址导入，URL 也显示原地址。
• 素材要求：以模型方素材库的要求为准，本站不另加限制。图片：jpeg、png、webp、bmp、tiff、gif、heic、heif，单张小于 30MB，宽高比（宽/高）0.4–2.5，宽和高 300–6000px；视频：mp4、mov，不超过 50MB，2–30 秒；音频：mp3、wav，2–30 秒。直接上传文件暂不支持 bmp、tiff，请用公网地址导入。
• 入库失败：导入时返回 400 asset_invalid 或稍后变为 Failed，原因见 message / FailReason。seedance-2-5 会写明原因并附错误码（如「内容未通过安全审核（InputImageSensitiveContentDetected…）」）；seedance-2-0-official 的模型方不给具体原因，审核不通过时也只返回上面的要求，格式、大小、尺寸都符合仍失败的，多半是内容未过审。
• 归属：素材只属于上传它的账号；引用别人的或已删除的素材返回 400，不扣费。其他平台或账号的素材 ID 不能直接用，导入一次即可拿到本站的素材 ID。
• 计费：上传和保存免费。视频素材按测得的时长计入参考视频时长，与直接传视频地址相同；图片和音频素材不影响价格。
• 数量与频率：不限每个账号的数量；素材库满了返回 429 asset_library_full，删掉不用的即可；上传繁忙时返回 429 asset_rate_limited，稍后重试。素材多请用批量导入，每个型号约每分钟导入 15 个。
• 批量导入：整批先检查：有一项不合法整批返回 400（param 指出哪一项，如 items[2].url），容量不够整批返回 429，都不排队。之后按顺序导入，上游繁忙自动重试。每项 Status：Queued / Importing；成功后带 Id，状态同素材本身（Active / Processing / Failed，删除后为 Deleted）；导入失败为 Failed 并带 Error.Code、Error.Message，改正后单独重提这几项。批次 Status 为 Running / Completed，附 SucceededCount、FailedCount、PendingCount。本地文件请用 POST /v1/assets 逐个上传。

curl http://localhost:3000/v1/assets \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "/YOUR_PERSON_IMAGE_PATH", "asset_type": "Image", "name": "人物正面", "model": "YOUR_VIDEO_MODEL_ID"}'
# 返回 {"Id": "asset-…", "Status": "Processing", …}，变成 Active 再用

curl http://localhost:3000/v1/video/generations \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "图片1中的人物转身看向镜头",
    "metadata": {
      "content": [
        {"type": "image_url", "image_url": {"url": "asset://YOUR_ASSET_ID"}, "role": "reference_image"}
      ]
    }
  }'

curl http://localhost:3000/v1/assets/batch \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "items": [
      {"url": "/YOUR_PERSON_IMAGE_PATH", "asset_type": "Image", "name": "人物正面"},
      {"url": "/YOUR_REFERENCE_VIDEO_PATH", "asset_type": "Video", "name": "动作参考"}
    ]
  }'
# 返回 {"BatchId": "batch_…", "Status": "Running", "TotalCount": 2, "PendingCount": 2, "Items": [{"Index": 0, "Status": "Queued", …}, …]}

curl http://localhost:3000/v1/assets/batch/YOUR_BATCH_ID \
  -H "Authorization: Bearer $DONGAPI_API_KEY"
# 完成后 {"Status": "Completed", "SucceededCount": 2, "FailedCount": 0,
#   "Items": [{"Index": 0, "Status": "Active", "Id": "asset-…", …}, {"Index": 1, "Status": "Active", "Id": "asset-…", …}]}
# 之后每次生成都用 asset://asset-… 引用，不用重新导入

火山方舟兼容接口（Seedance）

已按火山方舟 Ark 视频生成 API 接入的程序，可以只换 Base URL 和 API Key 直接调用 Seedance：Base URL 为 http://localhost:3000/api/v3，鉴权同样是 Authorization: Bearer $DONGAPI_API_KEY， model 填本站的 Seedance 模型 ID。请求经同一条视频链路处理，计费、分组、使用日志与 /v1/videos 相同。

请求体与方舟一致，差异如下：

• content：支持 text、image_url、video_url、audio_url 项及 role（first_frame、last_frame、reference_image、reference_video、reference_audio）；文本末尾的 --rs、--rt、--dur、--wm 等参数也会识别。图片和音频可用 base64；视频须为公网 URL。按 token 计费的型号可以用 asset:// 引用本站素材库，按秒计费的型号不支持；不支持 draft_task。
• duration：4–30 的整数（Seedance 2.0 为 4–15），不传为 5 秒；按 token 计费的型号另支持 -1（由模型决定时长），按秒计费的型号暂不支持 -1。
• ratio：16:9、9:16、1:1、4:3、3:4；不传或传 adaptive 时，有首帧图则按首帧图选最接近的比例，否则为 16:9。按 token 计费的型号另支持 21:9，adaptive 与首帧、尾帧按方舟原生方式处理。
• resolution：可不传；按秒计费的型号传入时须与模型 ID 中的分辨率一致，按 token 计费的型号可选该型号支持的分辨率（默认 720p）。
• generate_audio、watermark 照常生效；seed、camera_fixed 方舟仅 Seedance 1.0 支持，按秒计费的型号传入后忽略。
• 暂不支持并会返回 400：return_last_frame、draft、callback_url、tools、frames、output_format=mov、service_tier=flex、视频编辑与延长（omni_reference_task_type 为 edit / extend）。

查询返回的 status 为 queued、running、succeeded、failed、expired。成功后 content.video_url 是视频下载地址，无需鉴权：拿得到火山方舟官方的视频地址时原样返回官方地址（和方舟一样，生成后 24 小时内有效），否则返回本站带签名的地址。视频请在生成后 24 小时内下载保存；按秒计费的型号同时返回 usage.completion_tokens（按方舟口径：计费秒数 × 宽 × 高 × 24 / 1024），按 token 计费的型号返回实际结算的 tokens，duration 为 -1 的任务完成后返回实际时长。错误响应为方舟格式： {"error":{"code":"InvalidParameter","message":"…","param":"duration","type":"BadRequest"}}。

curl http://localhost:3000/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "content": [
      {"type": "text", "text": "小猫对着镜头打哈欠"},
      {"type": "image_url", "image_url": {"url": "/YOUR_FIRST_FRAME_PATH"}, "role": "first_frame"}
    ],
    "duration": 5
  }'

import os
from arkruntime import Ark  # pip install --upgrade arkruntime

client = Ark(base_url="http://localhost:3000/api/v3", api_key=os.environ["DONGAPI_API_KEY"])
task = client.content_generation.tasks.create(
    model="YOUR_VIDEO_MODEL_ID",
    content=[{"type": "text", "text": "小猫对着镜头打哈欠"}],
    ratio="16:9",
    duration=5,
)
print(client.content_generation.tasks.get(task_id=task.id).status)

OpenAI SDK

支持自定义 Base URL 的 OpenAI SDK 可直接接入。以下示例使用 Chat Completions。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DONGAPI_API_KEY"],
    base_url="http://localhost:3000/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "只回复 ok"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DONGAPI_API_KEY,
  baseURL: "http://localhost:3000/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "只回复 ok" }],
});
console.log(response.choices[0].message.content);