1. AE 脚本里批量画标注为什么绕不开 TextElement如果你在做 After Effects 的二次开发尤其是需要在一堆图层、合成或者时间点上批量生成文字标注那TextElement基本是绕不过去的一个对象。它属于 AE 脚本里 ExtendScript 体系下文本图层内容操作的核心入口能让你用代码直接控制文字内容、字体、字号、颜色、对齐方式甚至逐字动画属性。适合谁用适合那些不想手动一个个新建文本图层、复制粘贴标注内容的开发者比如做数据可视化标注、批量给素材打时间码、给模板自动填充说明文字的场景。我试过在一个 200 多个图层的小项目里手动加标注改到第 30 个就开始怀疑人生。后来换成脚本批量生成配合统一的 API 通道做配置管理整个流程才顺下来。这篇就按“先跑通 TextElement 标注生成再接上 TaoToken 统一 Key 配置骨架”的顺序来写你可以直接复制代码去改。需要提前说明的是AE 脚本运行在 ExtendScript 环境里语法是 ES3 级别的很多现代 JS 写法不能用比如let、箭头函数、模板字符串都不行。所以下面代码里你会看到大量var和字符串拼接这不是我偷懒是环境限制。2. 前置准备TaoToken 统一 Key 与 API 通道配置骨架在写标注代码之前先把通道配置搭好。因为实际项目里标注内容往往不是硬编码的可能来自外部数据、模型生成或者团队共享的配置。TaoToken 在这里的角色是提供一个统一的 Key 管理和 API 调用入口让你不用在每个脚本里散落一堆密钥。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。你需要先去控制台创建一个 Key控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后建议用两个配置文件来管理一个settings.json放运行时参数一个config.toml放通道和模型相关配置。这样做的目的是把“标注生成逻辑”和“通道调用逻辑”解耦后面换 Key 或者换模型不用动脚本主体。settings.json骨架大概长这样{ project: { name: ae-annotation-batch, version: 1.0.0 }, annotation: { fontName: SourceHanSansCN-Regular, fontSize: 24, fillColor: [1.0, 1.0, 1.0], positionOffset: [0, -40], layerPrefix: ANNO_ }, channel: { provider: taotoken, baseUrl: https://taotoken.net/api, timeoutMs: 15000, retry: 2 } }config.toml骨架[channel] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet [annotation] max_batch 50 refresh_after_add true注意api_key_env这一项意思是 Key 不直接写进配置文件而是从环境变量读取。这样你把脚本分享给同事的时候不会泄露密钥。设置环境变量的方式看你系统Windows 下可以用set TAOTOKEN_API_KEY你的keymacOS 或者 Linux 下用export TAOTOKEN_API_KEY你的key。配置好之后先做一个连通性验证动作确认通道是通的。可以用 curl 发一个最小请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet, messages: [{role: user, content: ping}], max_tokens: 8 }如果返回里有正常的 JSON 结构说明 Key 和通道都没问题。这一步别跳过后面脚本报错的时候你至少能确定不是通道的问题。模型对话的调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 可复制配置TextElement 创建与样式配置代码片段现在进入 AE 脚本主体。下面这段代码演示的是遍历当前合成里的所有图层给每个图层在指定位置创建一个文字标注标注内容取自图层名样式统一从配置里读。// AE ExtendScript - 批量创建 TextElement 标注 // 注意ES3 语法不能用 let/const/箭头函数 var settingsFile new File($.fileName.replace(/[^\/\\]$/, ) settings.json); var settings null; if (settingsFile.exists) { settingsFile.open(r); var raw settingsFile.read(); settingsFile.close(); settings eval(( raw )); } else { alert(settings.json 未找到使用默认配置); settings { annotation: { fontName: Arial, fontSize: 24, fillColor: [1, 1, 1], positionOffset: [0, -40], layerPrefix: ANNO_ } }; } var comp app.project.activeItem; if (!(comp instanceof CompItem)) { alert(请先打开一个合成); } else { app.beginUndoGroup(批量创建标注); var annoCfg settings.annotation; var created 0; for (var i 1; i comp.numLayers; i) { var layer comp.layer(i); // 跳过已经生成的标注层避免重复 if (layer.name.indexOf(annoCfg.layerPrefix) 0) { continue; } // 创建文本图层 var textLayer comp.layers.addText(layer.name); textLayer.name annoCfg.layerPrefix layer.name; // 获取 TextElement 并配置样式 var textProp textLayer.property(Source Text); var textDocument textProp.value; textDocument.font annoCfg.fontName; textDocument.fontSize annoCfg.fontSize; textDocument.fillColor annoCfg.fillColor; textDocument.justification ParagraphJustification.CENTER_JUSTIFY; textProp.setValue(textDocument); // 设置位置在原图层位置基础上加偏移 var srcPos layer.property(Position).value; var offset annoCfg.positionOffset; textLayer.property(Position).setValue([ srcPos[0] offset[0], srcPos[1] offset[1], srcPos[2] ]); // 标注层放到最上层 textLayer.moveToBeginning(); created; } app.endUndoGroup(); alert(标注创建完成共生成 created 个文本图层); }这段代码里有几个关键点值得展开说。第一comp.layers.addText()返回的是一个 TextLayer它的Source Text属性值是一个 TextDocument 对象你改完这个对象之后必须用setValue()写回去否则不生效。第二fillColor是 RGB 数组范围 0 到 1不是 0 到 255这个坑我踩过写 255 进去颜色会溢出成白色。第三moveToBeginning()把标注层移到最上面避免被其他图层挡住。如果你需要更精细的控制比如给标注加描边或者背景可以继续操作 TextDocument 的strokeColor、strokeWidth或者给文本图层加 Drop Shadow 效果。但注意AE 脚本里给文本加效果要用textLayer.Effects.addProperty()不是直接改 TextDocument。另外eval(( raw ))这种解析 JSON 的方式在 ExtendScript 里是常见做法因为原生JSON.parse在部分 AE 版本里不可用。如果你用的 AE 版本支持JSON.parse直接换掉更安全。4. 验证请求与成功结果跑通标注生成与通道调用代码写完之后先别急着上大项目拿一个只有三五个图层的测试合成跑一遍。操作步骤是打开 AE新建合成随便建几个纯色图层命名成有意义的名字比如“场景一”“场景二”。然后把上面的脚本保存成.jsx文件和settings.json放在同一个目录下通过文件 脚本 运行脚本文件执行。执行成功的话你会看到合成里多出了以ANNO_开头的文本图层每个图层的内容就是原图层名位置在原图层上方偏移 40 像素字体和颜色按配置来。同时会弹出一个提示框告诉你生成了几个标注。通道调用这块如果你只是本地生成标注其实不一定要调 API。但如果你想让标注内容由模型生成比如根据图层内容自动生成描述性文字那就需要在脚本里发请求。ExtendScript 本身没有 fetch得用XMLHttpRequest或者Socket。下面是一个用XMLHttpRequest调 TaoToken 通道的最小示例function callTaoToken(prompt) { var xhr new XMLHttpRequest(); xhr.open(POST, https://taotoken.net/api/v1/chat/completions, false); xhr.setRequestHeader(Content-Type, application/json); xhr.setRequestHeader(Authorization, Bearer $.getenv(TAOTOKEN_API_KEY)); var body JSON.stringify({ model: claude-sonnet, messages: [{ role: user, content: prompt }], max_tokens: 64 }); xhr.send(body); if (xhr.status 200) { var resp eval(( xhr.responseText )); return resp.choices[0].message.content; } else { return 调用失败: xhr.status; } }注意这里用的是同步请求open第三个参数为false因为 ExtendScript 里异步回调处理起来比较麻烦而且 AE 脚本执行时本来就是阻塞的。同步请求会卡住界面所以别在循环里对每个图层都调一次最好批量拼成一个 prompt 一次请求。验证成功的标志是脚本执行完标注图层正确生成通道返回的内容能写进标注文本里。如果通道返回慢或者超时先把timeoutMs调大或者减少单次请求的 token 数。5. 本篇常见错排查TextElement 不生效与通道报错第一个高频错误是textProp.setValue(textDocument)没写只改了textDocument对象但没写回属性结果图层上文字没变化。这个错误很隐蔽因为代码不报错只是没效果。记住TextDocument 是值对象改完必须 setValue。第二个是字体名写错。AE 里字体名必须和系统里安装的字体名完全一致比如“SourceHanSansCN-Regular”不能写成“思源黑体”。如果字体找不到AE 会回退到默认字体不报错但样式不对。你可以在 AE 的文本面板里手动选一次字体然后看脚本里textDocument.font读出来是什么照着写。第三个是颜色值范围。前面说过fillColor是 0 到 1 的浮点数组。如果你从别的地方拿到 0 到 255 的 RGB 值记得除以 255。第四个是通道报 401。这通常是 Key 没读到或者格式不对。检查环境变量TAOTOKEN_API_KEY是否设置成功在命令行里echo $TAOTOKEN_API_KEY看看有没有输出。另外注意 Authorization 头里Bearer后面有一个空格别漏了。第五个是 429 限流。如果你在循环里对每个图层都发一次请求很容易触发限流。解决办法是合并请求把多个标注内容拼成一个 prompt一次拿回所有结果再分配。或者加一个$.sleep(500)在请求之间但这样脚本会跑得很慢。第六个是 AE 脚本权限问题。有些系统下 AE 不允许脚本访问网络需要在首选项 脚本与表达式里勾选“允许脚本写入文件和访问网络”。这个选项默认可能是关闭的不勾的话XMLHttpRequest会直接失败。6. 接入与排障把配置骨架用起来配置骨架搭好之后日常使用其实就是改settings.json里的参数不用动脚本。比如换字体、调字号、改偏移量都在 JSON 里改。通道相关的换 Key、换模型在config.toml里改。这样团队协作的时候脚本可以进版本库配置文件单独管理。如果你在接入过程中遇到通道报错优先去 API Keys 页面确认 Key 状态入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果是要验证模型返回内容是否符合预期可以去模型对话页面直接试入口是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期做编码和 Agent 类任务的可以看 Coding Plan 页面入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后说一个实用技巧AE 脚本调试的时候别直接在大项目上跑。新建一个空合成放两三个图层把脚本里的循环范围改小确认逻辑对了再放开。另外app.beginUndoGroup()和app.endUndoGroup()一定要配对不然撤销栈会乱出问题的时候没法回退。