Lumina API
语言

统一 API 入口

如果你是第三方客户端、脚本、服务端或网关对接方，这页就是 Lumina 的统一入口。这里只说明 Lumina 对用户开放的 API、模型名和参数。

获取 API Key macOS / Linux 快速开始 Windows 快速开始

只看这里就够了

文本

大多数客户端通过 OpenAI 兼容或 Anthropic 兼容接口接入文本模型。

图片

图片模型统一通过 /v1/images/generations 和 /v1/images/edits 暴露；只支持聊天入口的客户端也可借道调用。

视频

视频模型统一通过 /v1/videos 系列异步接口暴露；聊天和图片接口不会承接视频模型。

基础信息

项值说明
API Originhttps://api.aiflow321.cnAnthropic 兼容客户端常用根地址。
OpenAI Base URLhttps://api.aiflow321.cn/v1OpenAI 兼容客户端常用，通常带 /v1。
API Keysk-xxxx在控制台令牌页面创建。
模型发现GET /v1/models建议客户端用这个接口动态拉取当前可用模型。

统一接入方式

OpenAI 兼容入口

  • GET https://api.aiflow321.cn/v1/models
  • POST https://api.aiflow321.cn/v1/chat/completions
  • POST https://api.aiflow321.cn/v1/responses
  • POST https://api.aiflow321.cn/v1/images/generations
  • POST https://api.aiflow321.cn/v1/images/edits
  • POST https://api.aiflow321.cn/v1/videos
  • POST https://api.aiflow321.cn/v1/videos/{task_id}/remix
  • GET https://api.aiflow321.cn/v1/videos/{task_id}
  • GET https://api.aiflow321.cn/v1/videos/{task_id}/content

Anthropic 兼容入口

  • POST https://api.aiflow321.cn/v1/messages
  • 适合 Claude Code、OpenClaw、Roo Code 等 Anthropic 模式客户端。

只支持聊天入口的客户端

  • 如果客户端只能发 chat/completions，也可以调用部分图片模型。
  • 关键是把媒体模型名放到 model 字段，并把提示词放在最后一条 user message 中。
  • 视频模型必须使用 /v1/videos 异步提交，不能走聊天或图片接口。

视频查询与预览

  • 提交视频任务后，先使用 GET /v1/videos/{task_id} 查询状态。
  • 任务完成后，响应中的 metadata.url 会指向 Lumina 的公开代理地址，通常是 https://api.aiflow321.cn/v1/videos/{task_id}/content。
  • 不要依赖第三方返回的原始视频地址；下载、网页预览和客户端播放都应使用 Lumina 返回的 metadata.url 或同一个 /content 地址。
  • /v1/videos/{task_id}/content 支持浏览器视频预览所需的 Range / If-Range 请求头；带 Range 时可能返回 206 Partial Content、Content-Range 和 Accept-Ranges。
  • API 客户端访问 /content 时需要携带 Authorization: Bearer sk-...；在 Lumina 网页内预览时可使用当前登录会话。
curl "https://api.aiflow321.cn/v1/videos/{task_id}" \
  -H "Authorization: Bearer sk-your-key"

curl "https://api.aiflow321.cn/v1/videos/{task_id}/content" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Range: bytes=0-" \
  --output result.mp4

文档范围

AA

固定档位拆分组。对外只暴露 AA-* 模型名，价格相关参数会被锁定。

ZZ

GPT 图片固定档位组。对外提供 low / medium / high 三个模型名，质量档位由模型名决定。

PP

视频固定档位组。对外提供两个视频模型，图生视频素材必须是可公网访问且带标准文件扩展名的 URL。

媒体模型文档

这里只保留当前客户端会直接看到的 3 组媒体模型：AA、ZZ 和 PP。选择模型名时，请优先以 GET /v1/models 的实时返回为准。

AA · 固定档位拆分组 展开详情 收起

AA 组对应固定档位拆分模型。/v1/models 只返回 AA-* 别名模型；对应基础模型不会继续直接暴露。

模型名格式 AA-<基础模型>-<档位>
模型发现 GET /v1/models
计费信息 以控制台为准
调用原则 价格相关参数锁定

对外模型与固定规则

分类可用模型锁定 / 说明调用提示
GPT 图片AA-gpt-image-2-low / medium / high锁 quality；禁止 output_psd=true选择模型名即可选择质量档位。
NanoBanana FastAA-nanobanana2-1k / 2k / 4k锁分辨率档位，size 只允许 9:16 / 16:9不传 size 时默认当前档位 16:9。
NanoBanana ProAA-nanobananapro-1k / 2k / 4k锁分辨率档位，size 只允许 9:16 / 16:9不传 size 时默认当前档位 16:9。
Veo 3.1 FastAA-veo31fast-720p / 1080p锁 output_resolution；duration 只允许 4 / 6 / 8；不支持输出数量参数优先出片速度。
Veo 3.1 RefAA-veo31ref-720p / 1080p锁 output_resolution；duration 只允许 4 / 6 / 8；不支持输出数量参数适合参考图、参考视频或关键帧素材。
Sora 2AA-sora2-720p只保留 720p；duration 只允许 4 / 8 / 12支持 negative_prompt。

NanoBanana 允许比例与尺寸

AA-nanobanana* 当前只允许 9:16 / 16:9。比例别名会按当前 1k / 2k / 4k 档位转换为固定尺寸；方图和其它比例会返回 400。

模型档位允许 size / 转换尺寸
AA-nanobanana2-1k9:16 -> 768x1376；16:9 -> 1376x768
AA-nanobanana2-2k9:16 -> 1536x2752；16:9 -> 2752x1536
AA-nanobanana2-4k9:16 -> 3072x5504；16:9 -> 5504x3072
AA-nanobananapro-1k9:16 -> 768x1376；16:9 -> 1376x768
AA-nanobananapro-2k9:16 -> 1536x2752；16:9 -> 2752x1536
AA-nanobananapro-4k9:16 -> 3072x5504；16:9 -> 5504x3072

关键字段

字段类型必填适用范围默认 / 别名说明示例
model string 是 所有调用 必须填写 AA-* 别名模型 不能直接调用对应基础模型。 AA-veo31fast-720p
prompt string 是 所有调用 - 生成提示词。 a cinematic fox running through neon rain
size string 否 图片 / 视频 nanobanana* 默认当前档位 16:9 nanobanana* 只允许 9:16 / 16:9 或其对应固定尺寸；视频模型不能借 size 改清晰度。 16:9
quality string 否 图片 由模型名决定 AA-gpt-image-2-* 会锁 low / medium / high；nanobanana* 会跟随档位映射 standard / hd。 medium
duration integer 否 视频 未传时自动取当前模型最长时长 veo31fast / veo31ref 只允许 4 / 6 / 8；sora2 只允许 4 / 8 / 12。 8
aspect_ratio / negative_prompt / generate_audio / reference_mode / image mixed 否 按模型能力透传 不影响固定档位 这些参数可以继续传，但不能修改价格相关参数。 aspect_ratio=16:9

调用规则

  • AA 组的基础模型会从 /v1/models 隐藏；如果仍直接调用基础模型，会返回 400。
  • AA-gpt-image-2-low / medium / high 只允许当前 quality，且禁止 output_psd=true。
  • AA-nanobanana2-* 与 AA-nanobananapro-* 只允许 9:16 / 16:9；方图和其它比例会返回 400。
  • VEO 仅支持 AA-veo31fast-* 和 AA-veo31ref-*；AA-veo31 不再暴露。
  • AA-veo31fast*、AA-veo31ref*、AA-sora2-720p 会锁 output_resolution；不能通过 size 或 output_resolution 改清晰度。
  • VEO 不支持输出数量参数；n、count、num_outputs、output_count、number_of_videos、video_count 会被拒绝。
  • 当前可用模型、额度和计费信息请以控制台及 GET /v1/models 的实时结果为准。

示例

AA 图片示例 
curl "https://api.aiflow321.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AA-nanobananapro-2k",
    "prompt": "a luxury product photo of a mechanical banana",
    "size": "16:9",
    "response_format": "url"
  }'
AA 视频示例 
curl "https://api.aiflow321.cn/v1/videos" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AA-veo31ref-1080p",
    "prompt": "a cinematic fox following the same framing",
    "aspect_ratio": "16:9",
    "duration": 8,
    "reference_mode": "image",
    "image": ["https://example.com/ref.png"]
  }'
ZZ · GPT 图片固定档位组 展开详情 收起

ZZ 组面向客户端暴露三个固定档位图片模型。选择哪个模型，就代表选择对应的图片质量档位。

对外模型 ZZ-gpt-image-2-low / medium / high
图片能力 generations / edits / chat 借道
质量档位 由模型名决定
返回地址 Lumina /v1/assets/...

对外模型与固定规则

分类可用模型锁定 / 说明调用提示
低档图片ZZ-gpt-image-2-low固定 low 质量；不要额外传 quality适合轻量生成。
中档图片ZZ-gpt-image-2-medium固定 medium 质量；不要额外传 quality适合常规生成。
高质量图片ZZ-gpt-image-2-high固定 high 质量；不要额外传 quality适合更高质量输出。

关键字段

字段类型必填适用范围默认 / 别名说明示例
model string 是 所有调用 三选一 选择 low、medium 或 high 模型名即可决定质量档位。 ZZ-gpt-image-2-medium
prompt string 是 所有调用 - 生成或编辑提示词。 a mechanical fox in neon city
size string 否 所有调用 默认 1024x1024 直接传 WIDTHxHEIGHT。 1536x1024
quality string 否 所有调用 由 model 决定 建议不要传；如果传入，必须和模型名档位一致。 medium
image / mask / reference_images mixed 按接口而定 edits / chat 多模态 有图时走 edits 支持 URL、data URI、纯 base64 或上传文件。 ["https://example.com/base.png"]

调用规则

  • 客户端只需要在 model 中选择 ZZ-gpt-image-2-low、ZZ-gpt-image-2-medium 或 ZZ-gpt-image-2-high。
  • quality 由模型名决定。为了避免计费和实际调用不一致，建议不要额外传 quality；如果传入不匹配的 quality，请求会被拒绝。
  • 只带文本时走 /v1/images/generations；带参考图时走 /v1/images/edits。
  • response_format=url 时，返回的是 Lumina 本地 /v1/assets/... 地址，可再次作为参考图使用。
  • 当前可用模型、额度和计费信息请以控制台及 GET /v1/models 的实时结果为准。

示例

ZZ 生成示例 
curl "https://api.aiflow321.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ZZ-gpt-image-2-high",
    "prompt": "a mechanical fox in neon city",
    "size": "1536x1024",
    "response_format": "url"
  }'
ZZ 聊天入口带图编辑 
curl "https://api.aiflow321.cn/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ZZ-gpt-image-2-medium",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "keep the same subject, change the background to rainy neon night"},
          {"type": "image_url", "image_url": {"url": "https://example.com/base.png"}}
        ]
      }
    ],
    "size": "1536x1024",
    "response_format": "url"
  }'
PP · 视频固定档位组 展开详情 收起

PP 组面向客户端暴露两个固定档位视频模型，支持文生视频、图生视频、首尾帧和多参考输入。

对外模型 PP-seedance-2-fast-beta-face / PP-seedance-2-beta-face
推荐入口 POST /v1/videos
输入类型 text_to_video / image_to_video / first_last_frame / multi_ref
多参考素材 图片最多 9 个；视频最多 3 个；音频最多 3 个
结果获取 /v1/videos/{task_id}/content

对外模型与固定规则

分类可用模型能力说明调用提示
快速人像视频PP-seedance-2-fast-beta-face4-15 秒；480p / 720p；支持文生/图生/首尾帧/多参考适合优先速度的任务。
高阶人像视频PP-seedance-2-beta-face4-15 秒；480p / 720p / 1080p；支持文生/图生/首尾帧/多参考适合更高分辨率任务。

关键字段

字段类型必填适用范围默认 / 别名说明示例
model string 是 所有调用 二选一 选择 PP-seedance-2-fast-beta-face 或 PP-seedance-2-beta-face。 PP-seedance-2-fast-beta-face
prompt string 是 所有调用 - 视频提示词，建议 1-2500 字符。multi_ref 下请在提示词中用 @image_file_1、@video_file_1、@audio_file_1 等引用素材。 use @image_file_1 as the character
mode string 否 所有调用 按素材自动推断 建议显式传 text_to_video、image_to_video、first_last_frame 或 multi_ref。multi_ref 至少提供 image_urls、video_urls、audio_urls 中的一类素材。 multi_ref
image_url string 图生视频必填 image_to_video - 单张参考图 URL，必须可公网访问，路径建议带 .jpg/.jpeg/.png/.webp 扩展名。 https://example.com/reference.png
image_urls array<string> 按模式而定 first_last_frame / multi_ref - 首尾帧或多参考图片 URL 列表。first_last_frame 通常传 2 张；multi_ref 最多 9 张，并在提示词中按 @image_file_1、@image_file_2 引用。每张图任一边需在 300-6000 px。 ["https://example.com/first.jpg","https://example.com/last.jpg"]
video_urls array<string> multi_ref 按需 multi_ref - 公开可访问的视频参考 URL，最多 3 个。总时长不超过 15 秒；单个视频至少 1.8 秒且不低于 409,600 pixels。提示词中按 @video_file_1 引用。 ["https://example.com/motion.mp4"]
audio_urls array<string> multi_ref 按需 multi_ref - 公开可访问的音频参考 URL，最多 3 个。提示词中按 @audio_file_1 引用。 ["https://example.com/music.mp3"]
ratio / aspect_ratio / size string 否 所有调用 建议显式传 ratio 可直接传 ratio，也可用 aspect_ratio 或 size=1280x720 让系统推断。允许 21:9、16:9、4:3、1:1、3:4、9:16、adaptive。 16:9
resolution / output_resolution string 否 所有调用 720p fast 支持 480p / 720p；beta 支持 480p / 720p / 1080p。 720p
duration / seconds integer 否 所有调用 模型默认值 单位秒，支持 4-15 秒；seconds 会按 duration 处理。 6
generate_audio boolean 否 按模型能力 模型默认值 需要模型生成或保留音频能力时使用；可显式传 true 或 false。 false
negative_prompt string 否 按模型能力 - 负向提示词，用于描述需要避免的画面元素。 blurry, low quality
auto_review boolean 否 按模型能力 模型默认值 需要显式控制任务审核行为时使用。 true
metadata object 否 任务透传 - 附加任务元数据，会随视频任务提交。不要放入密钥、令牌或个人敏感信息。 {"job_id":"demo-001"}

调用规则

  • 视频任务必须使用异步 /v1/videos 提交，再通过 GET /v1/videos/{task_id} 查询。
  • 不要把 PP 视频模型发到 /v1/chat/completions、/v1/images/generations 或 /v1/images/edits。
  • 图生视频建议显式传 mode=image_to_video 和 image_url；首尾帧传 mode=first_last_frame 和 image_urls；多参考传 mode=multi_ref，并至少提供一类 image_urls、video_urls 或 audio_urls。
  • 参考素材必须是公网可访问的 http(s) URL。图片路径建议带 .jpg/.jpeg/.png/.webp 等标准文件扩展名，响应 Content-Type 也要与素材类型一致。
  • 图片任一边需要在 300-6000 px；multi_ref 图片最多 9 个，视频最多 3 个，音频最多 3 个。
  • multi_ref 的视频参考总时长不超过 15 秒；单个视频至少 1.8 秒且不低于 409,600 pixels。
  • 不要使用 data:、base64、本地地址、临时中转地址或需要登录的 URL。
  • 真人或肖像图片可能因安全策略被拒绝；遇到失败时请更换素材或提示词。
  • 任务完成后通过 Lumina 的 /v1/videos/{task_id}/content 获取视频内容；查询响应里的 metadata.url 也会指向这个 Lumina 代理地址。
  • 当前可用模型、额度和计费信息请以控制台及 GET /v1/models 的实时结果为准。

示例

PP 文生视频示例 
curl "https://api.aiflow321.cn/v1/videos" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PP-seedance-2-fast-beta-face",
    "prompt": "a cinematic fox running through neon rain",
    "mode": "text_to_video",
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'
PP 图生视频示例 
curl "https://api.aiflow321.cn/v1/videos" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PP-seedance-2-fast-beta-face",
    "prompt": "animate the portrait with a subtle camera push-in",
    "mode": "image_to_video",
    "image_url": "https://example.com/reference.png",
    "ratio": "9:16",
    "resolution": "720p",
    "duration": 5
  }'
PP 多参考示例 
curl "https://api.aiflow321.cn/v1/videos" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PP-seedance-2-fast-beta-face",
    "prompt": "use @image_file_1 as the character, match the motion in @video_file_1, and follow the rhythm of @audio_file_1",
    "mode": "multi_ref",
    "image_urls": ["https://example.com/character.png"],
    "video_urls": ["https://example.com/motion.mp4"],
    "audio_urls": ["https://example.com/music.mp3"],
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 6
  }'
PP 查询和取视频 
curl "https://api.aiflow321.cn/v1/videos/{task_id}" \
  -H "Authorization: Bearer sk-your-key"

curl "https://api.aiflow321.cn/v1/videos/{task_id}/content" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Range: bytes=0-" \
  --output result.mp4

聊天入口调用图片模型

如果第三方客户端只有 /v1/chat/completions 入口，也可以直接通过 Lumina 调用图片模型；视频模型请使用异步 /v1/videos。

展开聊天入口参数详情
字段类型必填说明示例
model string 是 填支持聊天借道的图片模型名；视频模型请用 /v1/videos。 AA-gpt-image-2-medium / ZZ-gpt-image-2-medium
messages array 是 最后一条 user message 里的文本会作为媒体提示词。 [{"role":"user","content":"a mechanical fox in neon city"}]
messages[].content[].image_url / input_image array<object> 否 聊天型客户端如果支持多模态 content parts，可在这里附带参考图；图片模型会按编辑处理，url 结果返回 Lumina 本地 /v1/assets/... 地址。 [{"type":"image_url","image_url":{"url":"https://example.com/reference.png"}}]
size / quality / response_format mixed 否 图片模型相关的扩展字段仍然可以作为顶层字段一起传；视频模型请改用 /v1/videos。 size=1024x1024, quality=medium
  • 最后一条 user 消息文本会作为媒体提示词。
  • 图片扩展字段取值请参考上方 AA / ZZ 折叠文档；PP 视频字段请参考 PP 折叠文档。
  • 图片模型成功后，assistant.content 会返回图片 URL。
  • 视频模型需要先返回任务 ID，完成后再通过 /v1/videos/{task_id}/content 获取内容。

客户端能力矩阵

客户端类型推荐协议文本图片视频
Claude Code / OpenClaw / Anthropic 风格工具 Anthropic 兼容 支持 通常不直接支持 通常不直接支持
OpenAI 兼容桌面客户端 OpenAI 兼容 支持 视客户端而定 视客户端而定
只支持聊天入口的第三方客户端 OpenAI 聊天入口 支持 可借道 需 /v1/videos
脚本 / 后端服务 直接调 API 支持 支持 支持

最小调用示例

AA 图片 
curl "https://api.aiflow321.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AA-gpt-image-2-medium",
    "prompt": "a mechanical fox in neon city",
    "size": "1024x1024",
    "response_format": "url"
  }'
AA 视频 
curl "https://api.aiflow321.cn/v1/videos" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AA-veo31fast-720p",
    "prompt": "a cinematic mechanical fox running through neon rain",
    "aspect_ratio": "16:9",
    "duration": 8
  }'
ZZ 图片 
curl "https://api.aiflow321.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ZZ-gpt-image-2-high",
    "prompt": "a mechanical fox in neon city",
    "size": "1536x1024",
    "response_format": "url"
  }'
PP 图生视频 
curl "https://api.aiflow321.cn/v1/videos" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PP-seedance-2-fast-beta-face",
    "prompt": "animate the portrait with a subtle camera push-in",
    "mode": "image_to_video",
    "image_url": "https://example.com/reference.png",
    "ratio": "9:16",
    "resolution": "720p",
    "duration": 5
  }'
聊天入口调用 AA 图片模型 
curl "https://api.aiflow321.cn/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AA-gpt-image-2-medium",
    "messages": [
      {"role": "user", "content": "a mechanical fox in neon city"}
    ],
    "size": "1024x1024",
    "response_format": "url"
  }'

与现有教程的关系

  • 如果你是脚本、服务端、网关对接方，先看这页。
  • 如果你是 Claude Code、Cursor、Cherry Studio 等具体客户端用户，再去看对应客户端页面。
  • 模型列表、额度和计费信息会变化，请以控制台和 GET /v1/models 的实时返回为准。