通用接入

连接 Unicomp AI API

创建本人密钥后，先读取模型列表，再选择具体型号与已开放组合；示例、参数与价格随当前配置更新。

鉴权与地址

在密钥管理创建Key。正式 Base URL 为 https://www.unicompapi.com/v1（末尾包含 /v1），第三方应用也使用此地址。每次请求携带Authorization: Bearer <本人API Key>；不得把Key放在URL、公开代码或浏览器共享链接里。模型列表为GET /v1/models。

在服务端终端设置以下环境变量，替换密钥占位值；Python、Node.js 与 Shell 示例使用同一组变量。

Shell / curl

export UNICOMP_BASE_URL="https://www.unicompapi.com/v1"
export UNICOMP_API_KEY="<本人API密钥>"

先验证地址与密钥

设置 UNICOMP_BASE_URL（末尾含 /v1）和 UNICOMP_API_KEY。GET /v1/models 返回当前密钥可用的型号；空列表表示当前没有可调用型号。

示例语言

将接入地址与密钥放入服务端环境变量。此请求只读取模型列表，不生成内容。

Shell / curl

curl "$UNICOMP_BASE_URL/models" \
  -H "Authorization: Bearer $UNICOMP_API_KEY"

请求号与人民币计费

每次新业务请求生成并保存一个Idempotency-Key，同时将响应头X-Unicomp-Request-Id保存为REQUEST_ID；生成的幂等键保存为REQUEST_KEY。Shell 创建示例使用 Python 3 生成 UUID 并打印，执行前须已安装 Python 3。同原请求号与同内容用于追溯；内容或模型变化须新请求号。SDK设置maxRetries: 0，断线、超时或submission_unknown不自动重发。

文本、向量、重排按实际用量结算；图片、视频先报价并预留费用，结果和用量确认后交付至本人账户；公开分享另须审核。报价失败时不能创建付费任务；余额不足时，充值后继续结算同一任务。

断线或结果未知时，只查询原请求，不再次提交：以下命令使用之前保存的 REQUEST_ID 或 REQUEST_KEY，不重新生成 UUID。使用同一原Key读取GET /v1/requests/原请求编号；没有保存编号时，读取GET /v1/requests?idempotency_key=原幂等标识。返回原状态、已验证结果与用量、本单预留和账单；未确认或未计价结果不会显示为成功。同账号的其他Key也不能读取该原单。

Shell / curl

curl "$UNICOMP_BASE_URL/requests/$REQUEST_ID" -H "Authorization: Bearer $UNICOMP_API_KEY"
curl --get "$UNICOMP_BASE_URL/requests" --data-urlencode "idempotency_key=$REQUEST_KEY" -H "Authorization: Bearer $UNICOMP_API_KEY"

文字、向量或重排费用待结算时：沿原请求恢复

仅当原单返回canSettle: true时，才可向POST /v1/requests/原请求编号/settle发送空请求体，沿原单结算；余额不足先补余额，结果未确认仍保留原单。不发起新生成，不自动重试。

Shell / curl

curl -X POST "$UNICOMP_BASE_URL/requests/$REQUEST_ID/settle" -H "Authorization: Bearer $UNICOMP_API_KEY"

401检查Key；400检查字段及规格；402检查余额；409检查幂等内容或价格变化；503检查型号及服务可用状态。错误反馈保留原请求号，不提供密钥明文。

按任务选择协议

文字与多模态理解：POST /v1/chat/completions；stream:true为真实SSE。图片、视频、工具、思考与结构化输出按具体型号的已开放组合选择；完整历史续轮须保留原消息与工具结果。
OCR：仍为chat/completions，但单图PNG/JPEG dataURI且只非流式。不要对所有标称视觉模型套OCR协议。
向量：POST /v1/embeddings，输出向量；重排：POST /v1/rerank，输出索引和相关性分数。
个人素材：POST /v1/assets上传原二进制，GET /v1/assets读取本人列表，返回data.id供型号assetIds使用。原内容GET/HEAD /v1/assets/:id/content支持Range；仅个人Key，文件格式与所选模型的输入要求会分别检查。
图片：POST /v1/images/quote只读报价；POST /v1/images/generations创建原任务。
视频：POST /v1/videos/quote只读报价；POST /v1/videos创建原任务。媒体202返回平台任务JSON，按原GET轮询，结果交付后，content使用创建任务时的Bearer密钥读取。
H3动作：POST /v1/h3/tasks报价与提交；生成、编辑、理解分别使用对应参数。原单查询及结算见下方H3说明，不套普通视频创建协议。

图片与视频费用待结算时：沿原任务恢复

先用同一原个人Key读取GET /v1/images/:id或GET /v1/videos/:id。仅原响应给出settlement操作且billing.settlement_pending: true时，按其settlement.url结算：图片为POST /v1/images/:id/settle，视频为POST /v1/videos/:id/settle。两者都要求Content-Type: application/json，请求体不超过4096字节且不带查询参数。

JSON只接受三个字段：actual_amount须原GET的billing.actual_amount正安全整数，单位为人民币微元（1000000微元=1元）；price_version须原GET的billing.price_version；confirmation固定为settle_original_approved。不要使用报价金额替代实际金额，也不要添加模型、提示词、素材或新生成参数。结算时核对原任务、密钥、结果和用量，避免重复扣费；余额不足先补余额，再结算原单。

Shell / curl

curl -X POST "$UNICOMP_BASE_URL/images/$TASK_ID/settle" -H "Authorization: Bearer $UNICOMP_API_KEY" -H "Content-Type: application/json" --data "{\"actual_amount\":$ACTUAL_AMOUNT,\"price_version\":\"$PRICE_VERSION\",\"confirmation\":\"settle_original_approved\"}"
curl -X POST "$UNICOMP_BASE_URL/videos/$TASK_ID/settle" -H "Authorization: Bearer $UNICOMP_API_KEY" -H "Content-Type: application/json" --data "{\"actual_amount\":$ACTUAL_AMOUNT,\"price_version\":\"$PRICE_VERSION\",\"confirmation\":\"settle_original_approved\"}"

上面两行分别适用于图片和视频，只选择原任务对应的一行。保存原任务编号和返回账单状态；结果未知仅沿原GET查询，不重新生成。该结算动作不会重新生成作品。

H3：报价、动作与原单恢复

MiniMax-H3 具体型号、参数与报价说明 →。generate生成视频，regenerate编辑视频，understand返回文字。部分参数组合尚未开放，请先使用同一密钥获取报价，确认是否可以提交。

向POST /v1/h3/tasks发送operation: quote、model: MiniMax-H3、顶层action及其parameters，按型号要求携带描述和本人referenceAssets。仅报价closed_reasons为空且quoted_amount是已确认正整数时，原输入保持不变，以operation: submit再提交一次；请求头保存Idempotency-Key，请求体填写原expected_input_digest、expected_price_version、expected_quote_amount。金额单位为CNY_MICRO（1000000微元=1元），最终结算以任务返回的实际金额为准。

返回平台任务编号后，同原Key读取GET /v1/h3/tasks/:id查看保存的原状态；需要更新任务状态时显式使用GET /v1/h3/tasks/:id?refresh=true。只查询已经受理的原单，不再次POST生成。原终态、费用或输出未确认时保留原单及预留；FAILED状态不保证费用为零，请以返回的账单状态为准。

仅原响应给出结算操作及billing.settlement_pending: true时，向POST /v1/h3/tasks/:id/settle发送application/json，且无查询参数。三个字段为原billing.actual_amount正安全整数对应的actual_amount、原billing.price_version对应的price_version，以及固定confirmation: settle_original_h3。服务端会检查原密钥、任务结果和用量，避免重复扣费；不要用普通图片/视频的confirmation，也不携新描述或素材。

部分音频参考、作品再编辑或视频理解组合可能尚未开放，请以报价返回的具体限制为准。报价不允许提交时，不要自行填写金额或使用其他模式的价格。

查看每个型号的精确字段、枚举、价格与响应 →

接入代码

以下按当前可调用型号与已启用组合生成；完整字段、原工具结果续轮与素材限制请查看具体型号文档。

型号请求组合示例语言

将接入地址与密钥放入服务端环境变量。示例不会在网页自动执行；替换全部占位内容后，按实际调用用量计费。

Shell / curl

# 仅用于新请求；结果未知时查询原请求，不重新执行本段
# 需要 Python 3；打印的 REQUEST_KEY 请保存，供原单查询使用
REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
[ -n "$REQUEST_KEY" ] || exit 1 # UUID生成失败时停止
printf 'REQUEST_KEY=%s\n' "$REQUEST_KEY"
curl "$UNICOMP_BASE_URL/h3/tasks" \
  -H "Authorization: Bearer $UNICOMP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  --data '{
  "operation": "quote",
  "model": "MiniMax-H3",
  "action": "generate",
  "prompt": "白色背景上的橙色陶瓷杯",
  "parameters": {
    "resolution": "2K",
    "ratio": "16:9",
    "duration": 4,
    "generate_audio": true,
    "watermark": false
  }
}'

本组合的使用说明与限制

先报价，再使用相同Key和输入提交。若closed_reasons不为空，按返回原因调整；有效quoted_amount为正整数。
POST /v1/h3/tasks：先operation=quote，保存input_digest、price_version、quoted_amount；再operation=submit，携Idempotency-Key和对应expected字段。金额单位CNY_MICRO，1元=1000000微元。
GET /v1/h3/tasks/<任务UUID>查看原任务；refresh=true刷新已受理任务的状态。查询使用创建任务的同一Key，结果未知时不重复POST。
billing.settlement_pending=true时，向原任务/settle发送POST：{actual_amount:<billing.actual_amount>,price_version:<billing.price_version>,confirmation:已固定字符串settle_original_h3}。补足余额后结算原任务，不重新生成。
generate生成视频，regenerate重新生成视频，understand返回文字；action放在顶层。regenerate仅2K且generate_audio=true；understand的duration为4–15整数。referenceAssets填写本人素材ID、source与角色，不传远程URL。
从已成功视频重新生成时填写source_task_id=<本人原任务UUID>，不传prompt或referenceAssets。视频按输入音视频合计秒数和输出秒数计费，参考图片前5张免费；understand按输入和输出Token计费。先预留报价金额，完成后结算；余额不足时保留原结果等待补足。
视频完成后返回asset_id及私有content下载路径；understand返回text。失败或未知任务的扣费、预留和退款状态以原任务billing为准。

错误码与排查

HTTP 状态说明错误类别，error.code 与 error.message 说明具体原因。以下列出常见类别，具体代码以本次响应为准；流式开始后的错误与终态也须检查。

JSON

{"error":{"code":"INVALID_INPUT","message":"提交内容格式不正确"}}

HTTP	常见代码	处理方式
400 / 422	`INVALID_INPUT、INVALID_CHAT_SETTINGS、INVALID_FUNCTION_TOOLS、UNSUPPORTED_CAPABILITY`	字段、参数组合或工具消息顺序不正确，或当前能力未开放。按 error.message 修改；工具续轮保留原 assistant.tool_calls 和对应 tool 消息。
401	`UNAUTHENTICATED、API_KEY_INVALID`	检查 Base URL、Bearer 密钥、有效期和账号状态。网页登录与 API Key 分别验证。
402	`INSUFFICIENT_FUNDS`	余额不足；补足后查询原单，费用待结算时按原单操作。
403	`PERMISSION_DENIED、NATIVE_MODE_UNVERIFIED`	权限或所选能力组合未开放。模型能调用不代表每个工具、思考或输出组合都已支持；检查型号文档，勿把所有 403 当作 Key 错误。
404	`MODEL_NOT_FOUND、TASK_NOT_FOUND`	检查公开模型 ID 与本人原任务编号；不能用其他账号或其他 Key 读取原单。
409	`CONVERSATION_PENDING、CONVERSATION_KEY_MISMATCH、IDEMPOTENCY_CONFLICT`	上一轮未终结、会话授权变化或幂等内容冲突。查询上一轮；恢复原授权或新建聊天。
413 / 415	`BODY_TOO_LARGE、UNSUPPORTED_MEDIA_TYPE`	请求过大或文件格式不支持，按型号文档缩小输入或换受支持格式。
429	`RATE_LIMITED`	限流。等待后先核对原单状态，避免重复提交未知请求。
500 / 502 / 503 / 504	`INTERNAL_ERROR、UPSTREAM_ERROR、MODEL_UNAVAILABLE`	平台或上游异常。保留原请求号；已发送、超时或断线时查询原单，不自动再次生成。

错误反馈提供 HTTP、error.code、请求时间及 X-Unicomp-Request-Id。不要发送 Key、签名素材链接或完整个人内容。submission_unknown 是结果待核状态；“生成失败”“停止接收”和“费用已结算”分别查看，不据页面加载动画判断是否收费。

上游参数错误可参考阿里云官方错误码；平台请求号与供应商请求号分别保存，先通过后台原单关联排查。