概述

本文档为 Kickart OpenAPI【获取字体列表 API】的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地获取平台提供的字体素材列表，并将其应用于 AI 特效模板任务中，或故事版渲视频时指定字幕字体样式。

快速开始

仅需两步即可完成您的首次 API 调用：

申请 API Key：在火山-Kickart控制台获取用于 OpenAPI 请求的 API Key。

调用接口：根据本文档的指引，构造 HTTP 请求，并通过 API Key 进行鉴权，发起接口调用。

调用 API 须确认有权使用所提交的信息及内容，承诺上传的人像素材均为已授权虚拟人像，并已阅读且同意《虚拟人像合规承诺函》与***《合规承诺函》

OpenAPI域名

域名: https://Kickart.volces.com

APIKey 申请

请通过主账号登录Kickart首页，仅主账号可进行APIKey的管理和查看。

导航至 Kickart-apikey申请页面。

在左侧菜单中选择「API 密钥」模块，然后点击「+新建」按钮。

输入 API Key 名称后，点击「创建」按钮完成创建。

创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。

权限说明：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。

鉴权方式

所有 API 接口均采用基于 HTTP Header 的 Bearer Token 鉴权方案。您需要在每次请求的 Header 中附带 Authorization 和 Content-Type 字段。

Header	说明
Authorization	认证凭证。格式必须为 Bearer {API_KEY}，其中 {API_KEY} 需要替换为您在Kickart平台申请到的真实 API Key。示例: Bearer 1jkdislxdsldjgeouqllsj8ko8gssccx
Content-Type	请求体的内容类型。固定值为 application/json。

接口说明

获取字体列表

该接口用于分页获取平台提供的公开字体素材列表。返回的字体 media_id 可用于 AI 特效模板任务中需要指定字体的场景。

请求方法：POST

请求路径：/openapi/ai_effect/font_list

请求参数

字段名	类型	必填	示例	描述
page	int32	否	0	页码，从 0 开始。不传时默认为 0，须 ≥ 0。
perpage	int32	否	50	每页数量。不传时默认为 50，取值范围为 1–50。

响应参数

字段名	类型	描述
code	int32	状态码。0 表示请求成功。非 0 值表示请求失败，原因见 message 字段，具体含义请参考“错误码说明”章节。
message	string	状态描述信息。
request_id	string	本次请求的唯一标识符，可用于问题排查。
data	object	包含字体列表数据的对象，其结构见下文 data 结构。

data 结构

字段名	类型	描述
total	string	当前分类下字体素材的总数量（为避免大整数精度丢失，以字符串形式返回）。
medias	list<object>	字体素材列表，单项结构见下文 media 结构。

media 结构

字段名	类型	描述
media_id	string	字体素材的唯一 ID，可用于后续模板任务中指定字体。
name	string	字体名称。
preview_url	string	字体文件的下载地址。

cURL 请求示例

响应示例（成功）

响应示例（失败）

代码示例

Python	Java	Golang
import requests import json url = "https://Kickart.volces.com/openapi/ai_effect/font_list" payload = json.dumps({ "page": 0, "perpage": 50 }) headers = { 'Authorization': 'Bearer <your API_key>', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)	import java.io.IOException; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class FontListDemo { public static void main(String[] args) throws IOException, InterruptedException { String url = "https://Kickart.volces.com/openapi/ai_effect/font_list"; String jsonBody = """ { "page": 0, "perpage": 50 } """; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Authorization", "Bearer <your API_key>") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(jsonBody)) .build(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println("HTTP Status: " + response.statusCode()); System.out.println("Response Body:"); System.out.println(response.body()); } }	package main import ( "bytes" "fmt" "io" "net/http" ) func main() { url := "https://Kickart.volces.com/openapi/ai_effect/font_list" jsonBody := `{ "page": 0, "perpage": 50 }` req, err := http.NewRequest( "POST", url, bytes.NewBuffer([]byte(jsonBody)), ) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer <your API_key>") req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println("HTTP Status:", resp.StatusCode) fmt.Println("Response:", string(body)) }

错误码说明

所有接口的响应体中都包含 code 和 message 字段，用于指示请求的处理结果。当 code 为 0 时，表示业务处理成功。非 0 值表示出现了异常。

通用错误码

错误码	错误类型(标记用, 不会返回)	描述与处理建议
1300	AuthFailed	认证失败：API Key 无效、过期或未激活。请检查您的 API Key 是否正确，或在火山引擎控制台确认其状态。
1400	ParamErr	参数错误：请求中包含无效或缺失的参数。请对照文档检查请求体结构、字段类型和必填项。
1401	ConcurrentErr	并发超限：您当前的并发请求数超过了约定的上限。请降低请求频率，或联系商务代表调整并发额度。
1403	QuotaErr	无权限：您的账户没有调用此接口的权限。请联系企业管理员为您开通相关服务的访问权限。
1500	InternalErr	内部错误：服务端发生未知错误。请记录 request_id 并联系技术支持。

接口特定错误码

/openapi/ai_effect/font_list

错误码	错误类型(标记用, 不会返回)	描述与处理建议
0	Success	请求成功：字体列表已成功返回。
1300	AuthFailed	认证失败：请求头 Authorization 缺失或无效。请检查 API Key 是否正确传入。
1400	ParamErr	参数错误：page 须 ≥ 0，perpage 须在 1–50 之间。请对照文档检查入参。
1500	InternalErr	内部错误：查询字体列表失败。请记录 request_id 并稍后重试或联系技术支持。