打开控制台
WORKSPACE

接入指南

API Keys
DEVELOPER DOCUMENTATION

用文字、图片与视频，实现你的创意。

一组 API Key，统一的任务式生成流程。

仅开放已上架的 Nightfolio 文字、图片与动态模型。提交前会依页面显示的 Nightfolio 售价预留额度，成功后扣费。

快速开始

注册并验证邮箱、登录后建立 API Key、增加额度，再选择已开放的 Nightfolio 文字、图片或动态模型。账户可用额度必须足以支付本次报价。

Base URL https://developer.nightfolioai.com/v1

兼容范围：GET /v1/models 与 POST /v1/chat/completions 采用 OpenAI 格式。图片与视频使用 Nightfolio AI 异步任务（202 加轮询），不能直接替换 OpenAI SDK 返回格式；每个 Nightfolio 模型只开放其支持的能力参数。尚不支持 Claude Messages（/v1/messages）、Responses 与 OpenAI 图片编辑接口。

curl
curl "https://developer.nightfolioai.com/v1/images/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "nightfolio-image-4.5",
  "prompt": "A small ceramic vase on a warm gray background.",
  "size": "2848x1600",
  "image": [
    "asset://YOUR_REFERENCE_IMAGE_ID"
  ],
  "watermark": false
}'

身份验证

请在 Authorization 请求头带上你的 Nightfolio AI API Key，不需要供应商 Key。Key 应放在你自己的应用服务器；撤销后立即失效。

HTTP
Authorization: Bearer mh_YOUR_API_KEY

每次新的生成需要 Idempotency-Key（1–100 字符），请在送出前保存。重试同一操作时，必须使用原本的 Key 与内容。

模型与定价

GET /v1/models 只返回已开放的 Nightfolio 文字、图片与动态模型。模型目录会显示媒体模型的预设值与支持参数；每次请求会依规范化后的参数及页面显示的 Nightfolio 定价报价，并在提交前预留额度。

cURL
curl "https://developer.nightfolioai.com/v1/models" -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"

查看模型与固定参数 →

文字生成

POST /v1/chat/completions

已开放文字模型：nightfolio-text-2.0-mini、deepseek-v4.1-flash-1017 与 deepseek-v4-pro。采用 OpenAI Chat Completions 格式，支持系统消息与多轮历史；仅支持 n=1 和文字内容。

cURL
curl "https://developer.nightfolioai.com/v1/chat/completions" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"Explain how caching reduces inference costs."}],"thinking":{"type":"disabled"},"max_tokens":1024}'

DeepSeek 思考模式：thinking.type 传 enabled 或 disabled；开启时可设置 reasoning_effort 为 low、high 或 max，思考过程在 reasoning_content 中返回，最终答案在 content 中。不传时沿用上游默认思考设置，工作台默认关闭思考。平台输出上限为 65,536 tokens（包含思考），输入按序列化请求字节加消息开销保守限制为 1,000,000；暂未开放非文字输入。

Streaming + thinking
curl -N "https://developer.nightfolioai.com/v1/chat/completions" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"What is 17 times 19?"}],"thinking":{"type":"enabled"},"reasoning_effort":"low","max_tokens":2048,"stream":true}'

stream=true 返回 SSE 增量、用量和 [DONE]。最终用量可能与 choices 在同一条消息中；请分别处理 reasoning_content 与 content。服务会自动请求用量。DeepSeek 最长允许 10 分钟，流可能在部分文字之后返回错误事件。请保留 X-Request-ID，断流后先核对用量再决定重试，聊天请求不自动去重。

DeepSeek 的未缓存输入、缓存输入和输出均与所连接 MR 账户的目录牌价一致，零加价。模型目录展示当前费率及全部 UTC 时间规则（星期 1 为周一、7 为周日），请求开始时固定适用规则。费用 = 未缓存输入 × 输入费率 + 缓存输入 × 缓存费率 + 输出 × 输出费率，总额仅向上取整一次至 0.000001 美元。思考 token 已计入输出，不重复收费。提交前预留最高费用，收到有效用量后结算并释放剩余额度；缺少或矛盾的用量会保留预留款等待核对。上游成本按同一目录估算，与供应商账单的对账仍由人工完成。其他模型沿用各自公示价格。

参考素材

使用 Nightfolio API Key 即可上传图片、视频或音频，无须登录 Console。素材归属于你的账户，与 Console 素材库及同账户其他 Key 共用；其他账户无法列出、查询、删除或引用。

cURL
curl "https://developer.nightfolioai.com/v1/assets" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -F "file=@./reference.png" \
  -F "name=reference.png"

文件上传使用 multipart/form-data，每次一个 file。name 可选；type 自动识别，若传入则必须与文件一致。大小限制：图片 30 MB（JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC/HEIF），视频 200 MB（MP4/MOV），音频 15 MB（WAV/MP3）。每账户每分钟最多尝试上传 8 次，与 Console 共用限制。

URL import
curl "https://developer.nightfolioai.com/v1/assets" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-cdn.com/reference.png","type":"image","name":"reference.png"}'

URL 导入必填 url 与 type（image、video 或 audio），name 可选。必须使用公网可访问的 HTTPS URL（443 端口），不能带账号密码。远端素材会在处理阶段校验；大小未知时 size_bytes 为 null。

HTTP 202 Accepted
{
  "id": "YOUR_ASSET_ID",
  "object": "asset",
  "name": "reference.png",
  "type": "image",
  "status": "processing",
  "reference_url": "asset://YOUR_ASSET_ID",
  "size_bytes": 1024,
  "created_at": "2026-10-24T00:00:00.000Z",
  "updated_at": "2026-10-24T00:00:00.000Z"
}

保存返回的 ID，约每 2 秒查询 GET /v1/assets/{id}，直到 status 为 active 或 failed。只有 active 素材才能用于图片生成参考图、视频 input_references 或 frame_images。查询出错不代表上传失败，应重试查询。上传暂不支持 Idempotency-Key；若上传响应不确定，先列出已有素材，再决定是否重新上传。

cURL
curl "https://developer.nightfolioai.com/v1/assets/YOUR_ASSET_ID" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"
cURL
curl "https://developer.nightfolioai.com/v1/assets?type=image&status=active&page=1&page_size=20" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"

列表返回 object=list、data、total、page 和 page_size（1–100，默认 20）；type 与 status 筛选可选。列表显示已保存状态，processing 素材需逐个查询以刷新。API 返回用于生成的 reference_url，不返回下载地址。Console 上传的素材同样可通过此 API 查询和引用。

cURL
curl -X DELETE "https://developer.nightfolioai.com/v1/assets/YOUR_ASSET_ID" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"

删除返回 {id, object: "asset", deleted: true}，同一素材也会从 Console 移除。删除前请等待引用它的生成任务结束。未知或其他账户的 ID 返回 404；已撤销的 Key 或停用账户返回 401。

图片生成

POST /v1/images/generations

支持文字生图与参考图生图，每次输出一张图片。接口立即返回 HTTP 202 与 Nightfolio AI 任务 ID，通过 GET /v1/images/{id} 取得结果。这是 Nightfolio AI 的异步接口，并非 OpenAI 同步图片返回格式。

cURL
curl "https://developer.nightfolioai.com/v1/images/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "nightfolio-image-4.5",
  "prompt": "A small ceramic vase on a warm gray background.",
  "size": "2848x1600",
  "image": [
    "asset://YOUR_REFERENCE_IMAGE_ID"
  ],
  "watermark": false
}'

必填 model 与 prompt（1–8,000 字符）。可选的 size 与 watermark 必须与所选模型目录一致。image 可传一张 HTTPS／同账户 asset:// 参考图，或在模型上限内传入数组；Nightfolio Image 5.0 Pro 最多 10 张，其他已上架 Seedream 规格最多 14 张。本版不支持任意尺寸、多张输出、回调或 extra_body。

视频生成

POST /v1/videos/generations

文字生视频、多模态参考、首尾帧生成、视频编辑与延长共用此接口。返回 HTTP 202 后，查询 GET /v1/videos/{id}。Nightfolio 固定采异步流程，不需要传入 async。

cURL
curl "https://developer.nightfolioai.com/v1/videos/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "nightfolio-motion-2.0-fast",
  "prompt": "A slow camera movement through a sunlit forest.",
  "seconds": 4,
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "generate_audio": false
}'
模型系列时长解析度音频
Nightfolio Motion 1.0 / 1.55s720p关闭
Nightfolio Motion 2.04–15s480p / 720p / 1080p / 4ktrue / false
Nightfolio Motion 2.0 Fast / Mini4–15s480p / 720ptrue / false
Nightfolio Motion 2.54–30s480p / 720ptrue / false

Nightfolio Motion 使用 seconds 与 aspect_ratio 控制时长与比例，2.x 支持 16:9、9:16、1:1、4:3、3:4、21:9 与 adaptive。省略参数时保留向后兼容预设值：5 秒、720p、16:9、关闭音频；只要包含视频参考，就必须明确传入 seconds=-1。图片参考与首尾帧模式不支持 1080p。

input_references 可同时传入图片、视频与音频，role 必须分别为 reference_image、reference_video、reference_audio。Nightfolio Motion 2.0／Fast／Mini 最多 9 张图片、3 段视频、3 段音频（合计 15 个），且音频不可单独使用；Nightfolio Motion 2.5 最多 30 张图片、10 段视频、10 段音频（合计 50 个），也支持纯音频参考。URL 可使用同账户有效的 asset:// 素材或公开 HTTPS URL。

视频编辑
curl "https://developer.nightfolioai.com/v1/videos/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "nightfolio-motion-2.5",
  "prompt": "Edit video 1: replace the background with image 1. Keep the subject, timing, camera movement and audio unchanged.",
  "seconds": -1,
  "resolution": "480p",
  "aspect_ratio": "adaptive",
  "output_format": "mov",
  "input_references": [
    {
      "type": "video",
      "url": "asset://YOUR_VIDEO_ASSET_ID",
      "role": "reference_video"
    },
    {
      "type": "image",
      "url": "asset://YOUR_IMAGE_ASSET_ID",
      "role": "reference_image"
    }
  ]
}'

视频编辑与延长由提示词意图判定：请明确使用 edit、replace、remove、extend、continue 等动作，并指出视频 1、图片 1 等素材。Nightfolio Motion 2.5 的编辑／延长请使用 aspect_ratio=adaptive；包含非公众人物真人脸的参考素材应使用可信 asset:// 素材，而不是公开 URL。

首帧与尾帧
curl "https://developer.nightfolioai.com/v1/videos/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "nightfolio-motion-2.5",
  "prompt": "Move smoothly from the first frame to the last frame.",
  "seconds": 4,
  "resolution": "480p",
  "aspect_ratio": "adaptive",
  "frame_images": [
    {
      "frame_type": "first_frame",
      "image_url": "asset://YOUR_FIRST_FRAME_ASSET_ID"
    },
    {
      "frame_type": "last_frame",
      "image_url": "asset://YOUR_LAST_FRAME_ASSET_ID"
    }
  ]
}'

frame_images 可传入一个 first_frame，或一个 first_frame 加一个 last_frame。frame_images 与 input_references 不可同时使用；Nightfolio Motion 2.5 帧控制必须使用 aspect_ratio=adaptive。若还需要其他参考素材，请改用 input_references 并在提示词描述开场画面，但该模式无法保证精确首帧一致性。

素材上传支持图片最多 30 MB、MP4／MOV 视频最多 200 MB，以及 WAV／MP3 音频最多 15 MB。公开 HTTPS 参考网址在上游任务执行期间必须持续可访问。

任务与结果

JSON · accepted
{
  "id": "mh_image_JOB_ID",
  "object": "image",
  "model": "nightfolio-image-4.5",
  "status": "queued",
  "created_at": 1788696000,
  "charge": 0,
  "reserved": 50000,
  "billing_status": "processing",
  "result_expires_at": 0
}

上方金额仅供格式示意，不是报价。响应金额单位为 micro-USD：1 美元 = 1,000,000 单位。

cURL
curl "https://developer.nightfolioai.com/v1/images/mh_image_JOB_ID" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"
Status说明
queued等待提交
submitting正在提交生成
processing正在生成，请继续查询
completed结果已完成，费用已结算
failed生成失败，预留额度已释放
needs_review结果未明，额度保留待人工核对

完成后，图片位于 result.data[0].b64_json 或 url；视频位于 result.data[0].url。请及时保存：结果资料保留 24 小时，外部下载链接可能更早到期。只有任务所属账户可查询。

计费与重试

提交前会预留额度，成功后依任务保存的报价扣费一次；报价依所选模型与请求参数计算。确认失败会释放额度；提交中断或结果不明会保留额度待核对。不要因逾时而直接重新生成。

对 seconds=-1 的视频参考任务，Nightfolio 会先按保守上限预留；成功后再依供应商回报的实际输出 Token 计算较低的最终扣费。若缺少有效用量或实际用量超过预留，任务会进入 needs_review，不会猜测或直接超额扣款。

重试提交时沿用相同 Idempotency-Key 与内容；已取得 ID 就查询原任务。建议每 5–10 秒查询一次，遇到 429 延长间隔。每账户每分钟最多提交 12 次、查询 120 次，同时最多 4 个进行中请求。

错误处理

JSON
{
  "error": {
    "code": "model_not_published",
    "message": "This model is not published."
  }
}
HTTP处理方式
400检查必填栏位与固定规格
401检查 Key 或账户状态
402请管理员增加额度
404检查模型、任务 ID 与所属账户
409Idempotency-Key 与之前的内容冲突
429降低频率，不要重复建立任务
503模型未开放或服务尚未配置