快速开始

LocoPal 目前有两条常用路径：直接在 LocoPal Creation 创作，或使用 LocoPal Ai 的 API 接入自己的业务。

使用方式	入口	是否需要 API Key	适合场景
直接创作	LocoPal Creation	不需要	图片、视频、音频、短剧、素材与作品工作流
API 接入	LocoPal Ai	需要	把模型、图片、视频、音频或素材能力接入已有系统

两种方式共用同一个 LocoPal 账户、模型目录和计费体系。本页重点说明 LocoPal Ai 与 LocoPal Creation。

先读这一条：示例能否跑通取决于 Key 的分组

本页覆盖文本、图片、视频、音频和素材五类接口，但任何一把 API Key 能调用哪些模型，由它所属的调用分组决定。

例如一把只开通「图像」分组的 Key：GET /v1/models 只返回图像模型（如 gpt-image-2.5），此时照抄本页的文本、视频或音频示例会得到 503 model_not_found —— 这表示该模型不在你的分组里，而不是示例写错了。

所以：先执行第 5 步，用 /v1/models 看清这把 Key 实际能用什么，再回来看对应的示例。同一把 Key 在 locopalai.com 与 us-api.locopalai.com 上看到的模型集合可能不同，以你实际使用的地址为准。

第 1 步：注册或登录 LocoPal Ai

打开 LocoPal Ai。已有账号直接登录；没有账号时进入注册页。
当前注册页要求设置用户名和密码，并完成手机号短信验证。验证方式可能随安全策略调整，以注册页实际提示为准。
登录后确认账户余额、套餐额度或可用积分。使用 Creation 或 API 前都应先确认账户可用状态。

入口	用途
模型广场	查看模型名称、能力、参数、价格和可用分组
API 密钥	创建、停用和查看 API Key
使用日志	查询同步调用、用量与计费记录
任务日志	查询视频、音频等异步任务及制品
素材库管理	管理虚拟人物素材、真人素材、分组与状态
钱包	充值、查看套餐、订单和消费记录
LocoPal Creation	进入直接创作工作台，不需要创建 API Key

第 2 步：直接使用 LocoPal Creation

如果目标是直接生成内容，推荐先使用 Creation，不需要编写代码，也不需要创建 API Key。

打开 LocoPal Creation。
Creation 没有独立账号。未登录时页面会跳转到 LocoPal 登录，完成授权后自动返回 Creation，不需要再次输入密码。
在首页选择智能模式、AI 绘图、AI 视频或 AI 音频并输入需求；进入工作台后还可以使用短剧、作品、素材、提示词、词库和作品广场等入口。
需要保持人物、商品或风格一致时，在提交前上传参考图或选择已有素材。
提交后在当前页面查看任务状态、预览结果并下载或继续引用。刷新页面不会重新创建任务，不要对仍在执行的任务重复提交。

Creation 的模型可用范围和当前 LocoPal Ai 模型目录保持一致，调用消耗统一计入当前 LocoPal 账户。模型不可用时，先到 LocoPal Ai 模型广场确认该模型是否已在当前可用分组中。

第 3 步：接入 API 并创建 API Key

进入 LocoPal Ai 控制台「API 密钥」并点击创建。建议按「生产服务 / 测试环境 / 客户应用」分别创建密钥，便于按应用查看日志、限制额度并及时停用泄露的密钥。

创建时重点确认：

Key 名称用于区分调用方；
调用分组决定这把 Key 能看到和调用哪些模型；
额度与有效期用于限制异常消耗；
一把 Key 可调用模型、图片、视频、音频和素材接口，不需要为不同接口创建不同 Key。

API Key 只保存在服务端环境变量或密钥管理服务中，不要写入网页源码、移动端安装包、公开仓库、日志或截图。

第 4 步：准备基础地址

默认基础地址：

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

平台控制台还可能展示面向海外模型或特定网络环境的接入地址，例如：

https://us-api.locopalai.com

实际接入时应使用控制台当前展示的地址。LOCOPAL_BASE_URL 只写到域名，不要重复追加 /v1；接口路径本身已经包含 /v1 或 /api/v1。

第 5 步：查询当前 Key 可用的模型

这一步决定了后面哪些示例能跑

本页第 6–9 步是四类能力的示例。先跑这一步，看 /v1/models 返回了什么，就知道自己有权限用哪几个示例。没有返回的类别不必尝试 —— 直接跳到模型广场与计费确认分组，或联系平台支持开通。

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

请求里的 model 必须使用 data[].id，不要使用页面展示名称；
返回 "data": [] 表示当前 Key 所属调用分组没有可用模型，先确认分组配置或联系平台支持；
模型目录会随账户授权、接入地址和平台可用性变化，建议在服务启动、用户切换模型或收到「模型不可用」时重新查询；
同一把 Key 在 locopalai.com 与 us-api.locopalai.com 上看到的模型集合可能不同，使用哪个地址就以该地址的 /v1/models 为准；
模型能否调用以当前 Key 的 /v1/models 结果为准，不要写死模型名称。

用 `supported_endpoint_types` 判断该用哪个示例

data[].supported_endpoint_types 直接告诉你这个模型走哪类接口，据此选示例即可：

`supported_endpoint_types` 含	走哪个示例	典型接口
`chat` / `openai`（对话类）	第 6 步	`POST /v1/chat/completions`
`image-generation`	第 7 步	`POST /v1/images/generations`
视频类（`video-generation` 等）	第 8 步	`POST /v1/video/generations`
音频类（`tts` 等）	第 9 步	`POST /v1/audio/speech`

一个模型的 supported_endpoint_types 可能同时含多项，表示它可以用多种接口调用。

第 6 步：第一次文本调用

调用前请先确认该模型在你的分组内

需要 Key 的分组里有文本（对话）模型。若该分组只有图像模型，本步会返回 503 model_not_found —— 这是分组权限问题，不是请求写错了。

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

成功时从 choices[0].message.content 读取文本，并保存响应里的 usage 用于对账。推理模型可能把 max_tokens 全部消耗在 completion_tokens_details.reasoning_tokens，此时 message.content 为空且 finish_reason 为 length；提高输出上限或改用非推理模型后再试。开启 stream: true 后按 SSE 逐段读取，读到 [DONE] 结束。

第 7 步：第一次图片调用

建议

图像是独立的分组权限，与文本、视频、音频互不影响。只开通图像分组时，本页其余示例都会失败，但这一步可以正常出图。

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

响应结果通常在 data[] 中返回 url 或 b64_json。返回 URL 可能是短期地址，应尽快转存；size、quality 和 response_format 都取决于当前图片模型，部分 GPT Image 模型会拒绝 response_format 并返回 unknown_parameter，此时应移除该字段。图片作为后续视频参考时，先用素材库接口入库并等待状态为 Active，再使用 asset://<asset_id> 引用。

第 8 步：第一次视频调用

调用前请先确认该模型在你的分组内

需要 Key 的分组里有视频模型。视频、图像、文本是相互独立的分组权限：只开通图像分组时，本步返回 503 model_not_found，而第 7 步仍然可以出图。

视频是异步任务：创建接口返回任务 ID，查询接口返回进度和结果。

POST /v1/video/generations 与 POST /v1/videos 使用同一套请求体和响应格式，任选一种即可；旧调用路径会由平台自动按视频任务插件处理。

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

{
  "created_at": 1789567067,
  "id": "task-public-id",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task-public-id"
}

创建响应只应依赖 id / task_id、status、model 和 created_at；object、progress 等字段可能在首次查询后才出现，不能把它们当作创建成功的必要条件。

保存创建响应里的 id，再查询同一个任务：

export LOCOPAL_TASK_ID="创建响应里的 id"

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

任务成功后读取 metadata.url 下载或播放结果。平台优先返回上游原始视频 URL；如果上游没有返回可读取地址，才使用平台制品地址兜底。上游返回的视频参数可能包含：

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800
}

以上字段中，duration_secs 为时长；expires_at 只在对应上游返回时出现；其他视频参数同样只在模型和上游实际返回时出现。拿到任务 ID 后即使本地等待超时，也只能继续查询原任务，不要重新创建，否则会产生重复任务和费用。

如果查询结果 status 为 failed，读取同一响应里的 error.code 和 error.message。视频任务终态失败通常使用 video_generation_failed，error.message 是平台清理后的可读原因，不要再解析其中的 JSON：

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

第 9 步：第一次文本转语音调用

调用前请先确认该模型在你的分组内

需要 Key 的分组里有音频（TTS）模型。本步与图像分组无关，只开通图像分组时会返回 503 model_not_found。

平台提供 OpenAI 兼容的 POST /v1/audio/speech 接口。是否可用取决于当前 API Key 的分组和模型目录；支持的音色、格式与速度参数以实际模型为准。

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

成功响应的正文是二进制音频，不是 JSON；示例用 --output 保存为 speech.mp3。其他音频任务的异步状态与制品可在「任务日志」中查询。

第 10 步：第一次素材调用

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

保存 data.group.id，提交图片并轮询状态：

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url 使用可从公网直接下载的 http(s) 地址，也可以按接口限制提交 data_url。data.asset.status 变为 Active 后，即可在视频请求中用 asset://<asset_id> 引用。完整参数与错误说明见素材库接口。

第 11 步：真人素材（可选）

真人素材必须由本人用手机扫码完成采集和授权，不能用普通图片上传代替。控制台流程是「素材库管理 → 新建分组 → 真人素材 → 生成二维码 → 本人扫码 → 已完成扫码，开始同步」；接口流程见创建真人扫码会话。

下一步

想看什么	去哪一页
LocoPal Ai 控制台功能	平台功能指南
LocoPal Creation 创作流程	LocoPal Creation（创作平台）
API 平台、分组与任务日志	LocoPal Ai（API 平台）
有哪些接口	接口总览
认证、基础地址、分页等公共约定	认证与基础规范
模型目录与文本对话	模型与文本接口
图片生成	图片生成接口
视频生成、多图与参考视频	视频生成接口
素材分组、素材状态、真人授权	素材库接口
端到端接入示例	人像素材与参考视频接入流程
报错排查	错误码与排查

本页目录