linkfox-aigc-textgen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI 生文

AI Text Generation

使用大语言模型根据提示词生成文本内容，支持传入图片, 视频等进行图文结合，视频文本理解和分析。

Uses large language models to generate text content based on prompts, supporting combined understanding and analysis of text with images and videos by passing in image and video URLs.

核心特点

Core Features

双模型选择：快速响应（GEM_3_FLASH）和高质量复杂分析（GEM_3_1_PRO）。
图文/视频内容结合：
```
imageUrls
```
同时支持图片与视频 URL；图片最多 10 张，视频通常传 1 个。
思考深度可控：4 级 thinkingLevel 控制推理深度。
异步两步调用：创建任务后立即返回 taskId，客户端轮询查询结果，避免长耗时同步超时。

Dual Model Options: Fast response (GEM_3_FLASH) and high-quality complex analysis (GEM_3_1_PRO).
Combined Image/Video/Text Content:
```
imageUrls
```
supports both image and video URLs; maximum 10 images, usually 1 video.
Controllable Thinking Depth: 4 levels of thinkingLevel to control reasoning depth.
Asynchronous Two-Step Call: Returns taskId immediately after creating a task, and the client polls for results to avoid long-time synchronous timeout.

模型说明

Model Description

模型（model）	说明	适用场景
GEM_3_FLASH	快速响应（默认）	常规文案、简单分析、翻译
GEM_3_1_PRO	高质量复杂分析	深度分析、长文写作、复杂推理

Model	Description	Applicable Scenarios
GEM_3_FLASH	Fast response (default)	General copywriting, simple analysis, translation
GEM_3_1_PRO	High-quality complex analysis	In-depth analysis, long-form writing, complex reasoning

思考等级

Thinking Levels

thinkingLevel	说明
minimal	接近无思考（GEM_3_1_PRO 不支持）
low	低思考
medium	平衡
high	最大推理深度

thinkingLevel	Description
minimal	Almost no thinking (not supported by GEM_3_1_PRO)
low	Low thinking depth
medium	Balanced
high	Maximum reasoning depth

参数概览

Parameter Overview

必填字段：
```
prompt
```
、
```
imageUrls
```
（无图片且无视频时传空数组
```
[]
```
）、
```
thinkingLevel
```
（必须显式传入，建议默认
```
minimal
```
）
媒体 URL 约定：图片与视频 URL 均通过
imageUrls
传递（如视频分析传
```
["https://example.com/ref.mp4"]
```
）；勿使用未文档化字段（如
```
videoUrl
```
、
```
videoUrls
```
）

完整参数表、响应字段结构与错误码，见

references/api.md

。

Required Fields:
```
prompt
```
,
```
imageUrls
```
(pass empty array
```
[]
```
when there are no images or videos),
```
thinkingLevel
```
(must be explicitly passed, default
```
minimal
```
is recommended)
Media URL Convention: Both image and video URLs are passed via
```
imageUrls
```
(e.g., pass
```
["https://example.com/ref.mp4"]
```
for video analysis); do not use undocumented fields (such as
```
videoUrl
```
,
```
videoUrls
```
)

Complete parameter table, response field structure and error codes can be found in

references/api.md

调用方式

Calling Methods

采用异步两步模式（与 imagegen 一致）：

创建任务：
```
POST /aigc/textGenAsync
```
→ 返回
```
taskId
```

轮询查询：

POST /aigc/textTaskQuery

→ 返回

PROCESSING

SUCCESS

FAILED

Python 脚本（内部已封装创建+轮询，传参方式不变）：
- ```
python scripts/aigc_textgen.py --stdin
```
  — 推荐，从 stdin 读取 JSON 参数，避免 shell 转义问题（如
```
python scripts/aigc_textgen.py --stdin < params.json
```
  ）
- ```
python scripts/aigc_textgen.py --stdin --content-only
```
  — 只输出 content 文本（同样已是单行）
- ```
python scripts/aigc_textgen.py '<JSON 参数>' [--inline]
```
  — 简单场景直传（prompt 含换行符时禁用）

轮询策略：单次 HTTP 超时 150 秒；轮询间隔从 10 秒起递减至 5 秒；总轮询时长最长 600 秒。完整参数/响应/错误码见
references/api.md
。

换行符压平默认开启（无需任何 flag）：所有输出模式下，content 的换行都会自动替换为单字符
⏎
（U+23CE），整段 content 变成单行；
--content-only
只是改变"输出 content 文本 vs 完整 JSON"，不影响该压平行为。

Adopts asynchronous two-step mode (same as imagegen):

Create Task:
```
POST /aigc/textGenAsync
```
→ Returns
```
taskId
```

Poll for Results:

POST /aigc/textTaskQuery

→ Returns

PROCESSING

SUCCESS

FAILED

Python Scripts (internally encapsulates creation + polling, parameter passing remains the same):
- ```
python scripts/aigc_textgen.py --stdin
```
  — Recommended, reads JSON parameters from stdin to avoid shell escape issues (e.g.,
```
python scripts/aigc_textgen.py --stdin < params.json
```
  )
- ```
python scripts/aigc_textgen.py --stdin --content-only
```
  — Only outputs content text (already a single line)
- ```
python scripts/aigc_textgen.py '<JSON parameters>' [--inline]
```
  — Directly pass parameters for simple scenarios (disabled when prompt contains line breaks)

Polling Strategy: Single HTTP timeout is 150 seconds; polling interval decreases from 10 seconds to 5 seconds; maximum total polling duration is 600 seconds. Complete parameters/responses/error codes can be found in
references/api.md
.

Line Break Flattening is Enabled by Default (no flag required): In all output modes, line breaks in content are automatically replaced with the single character
⏎
(U+23CE), turning the entire content into a single line;
--content-only
only changes "output content text vs complete JSON", and does not affect this flattening behavior.

输出契约（其他 agent 按此解析）

Output Contract (other agents parse according to this)

stdout 只放机器数据，始终可
json.loads
（
```
--content-only
```
例外，其 stdout 是纯文本 content）：
- 默认（小结果）/
```
--inline
```
  ：stdout = 完整响应 JSON
- 大结果：stdout = JSON 信封
```
{"ok":bool, "truncated":true, "savedPath":"<路径>", "bytes":int, "content":"<单行文本>"}
```
所有提示/摘要/诊断（CHAIN-HINT、Saved full response、summarize）一律走 stderr，不污染 stdout。
退出码：成功
```
0
```
；失败（网络错误 /
```
errcode
```
非 200 /
```
status==FAILED
```
）非
```
0
```
—— agent 应优先用退出码判错。

读数据建议：小结果直接

json.loads(stdout)

取

content

；大结果读 stdout 信封的

content

（或按

savedPath

用

jq

抽完整字段），避免整份 JSON 进入上下文。

Only machine data is placed in stdout, which can always be
json.loads
(exception for
```
--content-only
```
, where stdout is plain text content):
- Default (small result) /
```
--inline
```
  : stdout = complete response JSON
- Large result: stdout = JSON envelope
```
{"ok":bool, "truncated":true, "savedPath":"<path>", "bytes":int, "content":"<single-line text>"}
```
All prompts/summaries/diagnostics (CHAIN-HINT, Saved full response, summarize) go to stderr to avoid polluting stdout.
Exit Code: Success
```
0
```
; Failure (network error /
```
errcode
```
not 200 /
```
status==FAILED
```
) non-0 — agents should prioritize using exit codes to judge errors.

Data Reading Suggestion: For small results, directly use

json.loads(stdout)

to get

content

; for large results, read the

content

from the stdout JSON envelope, or extract complete fields using

jq

according to

savedPath

, to avoid the entire JSON entering the context.

解决认证和积分问题

Resolving Authentication and Credit Issues

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

When the following exceptions occur, guide users to resolve them using references/onboarding.md:

异常情况

Exception Scenarios

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

API Key Not Configured: Environment variables
```
LINKFOX_AGENT_API_KEY
```
and
```
LINKFOXAGENT_API_KEY
```
are not configured.
Response with 401 or 402 Status Code
Response Indicates Insufficient Credits or Balance: Message contains "insufficient credit balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/need to recharge/please recharge", or similar meanings.

自动链式调用决策规则

Automatic Chain Call Decision Rules

Agent 必须遵循以下决策树，读到规则即自动执行，无需用户逐步指令。

用户需求后续是否涉及 作图 / 生图 / 换模特 / 视频 / imagegen / videogen？
│
├─ YES ──→ 使用 --content-only 模式（换行符已压平为单字符 ⏎，可安全内联拼接）
│           捕获 stdout → 内联拼进下游参数 JSON → 调用下游 Skill
│
└─ NO  ──→ 使用默认模式
            小结果 → json.loads(stdout) 取 content
            大结果 → 读 stdout JSON 信封的 content，或按 savedPath 用 jq 提取

Agents must follow the following decision tree, and automatically execute upon reading the rules without requiring step-by-step user instructions.

Does the user's subsequent request involve image generation / text-to-image / model replacement / video / imagegen / videogen?
│
├─ YES ──→ Use --content-only mode (line breaks have been flattened to single character ⏎, which can be safely inline concatenated)
│           Capture stdout → inline concatenate into downstream parameter JSON → call downstream Skill
│
└─ NO  ──→ Use default mode
            Small result → json.loads(stdout) to get content
            Large result → read content from stdout JSON envelope, or extract using jq according to savedPath

换行符占位符约定（核心机制）

Line Break Placeholder Convention (Core Mechanism)

content

通常含真实换行符，直接进 shell 变量或拼接 JSON 会断行。脚本默认（任何模式，无需 flag）把 content 的换行符统一替换为单字符

⏎

（U+23CE），同时覆盖真实换行控制符与字面量

\n

两种形态：

```
⏎
```
在 shell 单引号与 JSON 字符串中均无需转义，整段 content 变成单行，可被变量安全捕获、内联拼接；
下游 AIGC 脚本（imagegen / videogen / videogen-multi）解析参数后会自动把
⏎
还原为换行符（各 AIGC 脚本内联的
```
decode_nl_in_obj
```
），因此文本无损传递；
整段 content 变为单行后，可直接捕获进 shell 变量并内联拼接进下游参数 JSON，无需中间文件。

content

usually contains real line breaks, which will cause line breaks when directly put into shell variables or concatenated into JSON. The script by default (any mode, no flag required) replaces all line breaks in content with the single character

⏎

(U+23CE), covering both real line break control characters and literal

\n

forms:

```
⏎
```
does not need to be escaped in shell single quotes and JSON strings, turning the entire content into a single line that can be safely captured by variables and inline concatenated;
Downstream AIGC scripts (imagegen / videogen / videogen-multi) will automatically restore
⏎
to line breaks after parsing parameters (via
```
decode_nl_in_obj
```
inline in each AIGC script), so text is transmitted losslessly;
After the entire content becomes a single line, it can be directly captured into a shell variable and inline concatenated into downstream parameter JSON without intermediate files.

标准两步链式调用（imagegen / videogen / 任意 AIGC Skill）

Standard Two-Step Chain Call (imagegen / videogen / any AIGC Skill)

bash

undefined

bash

undefined

── Step 1：生文，--content-only 直接拿到单行 content（换行已是 ⏎），捕获进变量 ──────

── Step 1: Generate text, use --content-only to directly get single-line content (line breaks are already ⏎), capture into variable ──────

PROMPT=$(python scripts/aigc_textgen.py --stdin --content-only < textgen_params.json)

── Step 2：内联拼接进下游参数并调用下游 Skill（jq 负责正确的 JSON 转义） ───────────

── Step 2: Inline concatenate into downstream parameters and call downstream Skill (jq handles correct JSON escaping) ───────────

PARAMS=$(jq -nc --arg p "$PROMPT"
'{prompt:$p, imageUrls:["https://example.com/ref.jpg"], provider:"BANANA_PRO", outputNum:1, resolution:"1K", aspectRatio:"1:1"}') python ../linkfox-aigc-imagegen/scripts/aigc_imagegen.py "$PARAMS"

PARAMS=$(jq -nc --arg p "$PROMPT"
'{"prompt":$p, "imageUrls":["https://example.com/ref.jpg"], "provider":"BANANA_PRO", "outputNum":1, "resolution":"1K", "aspectRatio":"1:1"}') python ../linkfox-aigc-imagegen/scripts/aigc_imagegen.py "$PARAMS"

下游脚本接收后自动把 ⏎ 还原为换行符

Downstream script automatically restores ⏎ to line breaks after receiving


> 没有 `jq` 时，可直接把 `$PROMPT` 内联进单引号 JSON：因 `⏎` 无需转义且已无真实换行，
> 也能安全拼接（前提是 content 内不含双引号；含双引号时优先用 `jq`）。


> Without `jq`, you can directly inline `$PROMPT` into single-quoted JSON: since `⏎` does not need to be escaped and there are no real line breaks, it can also be safely concatenated (provided that content does not contain double quotes; use `jq` first if it does).

各下游 Skill 的关键参数参考

Key Parameter Reference for Each Downstream Skill

下游 Skill	关键字段（按需调整，prompt 由上游注入）
linkfox-aigc-imagegen	`{"imageUrls":[...],"provider":"BANANA_PRO","outputNum":1,"resolution":"1K","aspectRatio":"1:1"}`
linkfox-aigc-videogen	`{"imageUrls":[...],"model":"WAN2_1","outputNum":1,"resolution":"720P","duration":5}`
linkfox-aigc-imagegen-cloth	`{"imageUrls":[...],"outputNum":1,"aspectRatio":"1:1"}`
linkfox-aigc-imagegen-product	`{"imageUrls":[...],"outputNum":1,"aspectRatio":"1:1"}`

Downstream Skill	Key Fields (adjust as needed, prompt is injected by upstream)
linkfox-aigc-imagegen	`{"imageUrls":[...],"provider":"BANANA_PRO","outputNum":1,"resolution":"1K","aspectRatio":"1:1"}`
linkfox-aigc-videogen	`{"imageUrls":[...],"model":"WAN2_1","outputNum":1,"resolution":"720P","duration":5}`
linkfox-aigc-imagegen-cloth	`{"imageUrls":[...],"outputNum":1,"aspectRatio":"1:1"}`
linkfox-aigc-imagegen-product	`{"imageUrls":[...],"outputNum":1,"aspectRatio":"1:1"}`

使用指引

Usage Guidelines

模型选择：简单任务用
```
GEM_3_FLASH
```
（默认，响应快）；复杂分析、长文写作用
```
GEM_3_1_PRO
```
。
提示词：最大 10 万字符，描述越具体效果越好。
图片/视频输入：通过
```
imageUrls
```
传入媒体 URL。纯文本用
```
[]
```
；图片理解传 1–10 张图；视频理解通常传 1 个视频 URL（如
```
.mp4
```
）。复杂视频分镜/内容分析建议
```
GEM_3_1_PRO
```
+
```
thinkingLevel: low
```
。
思考等级：需要快速响应选
```
minimal
```
/
```
low
```
；需要深度推理选
```
high
```
。
视频失败兜底：若返回视频不可读、媒体访问失败、
```
10005
```
或内容为空，应抽帧为图片后再传入
```
imageUrls
```
（参见下游业务 skill 的抽帧流程）。

Model Selection: Use
```
GEM_3_FLASH
```
(default, fast response) for simple tasks; use
```
GEM_3_1_PRO
```
for complex analysis and long-form writing.
Prompts: Maximum 100,000 characters; the more specific the description, the better the effect.
Image/Video Input: Pass media URLs via
```
imageUrls
```
. Use
```
[]
```
for plain text; pass 1–10 images for image understanding; usually pass 1 video URL (e.g.,
```
.mp4
```
) for video understanding. For complex video shot/ content analysis, it is recommended to use
```
GEM_3_1_PRO
```
+
```
thinkingLevel: low
```
.
Thinking Level: Choose
```
minimal
```
/
```
low
```
for fast response; choose
```
high
```
for in-depth reasoning.
Video Failure Fallback: If the response indicates the video is unreadable, media access failed,
```
10005
```
or empty content, extract frames into images and pass them into
```
imageUrls
```
(refer to the frame extraction process of downstream business skills).

示例

Examples

1. 基础文本生成

json

{"prompt": "Write a compelling product description for a wireless bluetooth speaker, highlighting portability and sound quality", "imageUrls": [], "thinkingLevel": "minimal"}

2. 图片 + 文本结合分析

json

{"prompt": "分析这张商品主图的构图和卖点表达", "imageUrls": ["https://example.com/product-main.jpg"], "model": "GEM_3_1_PRO", "thinkingLevel": "high"}

3. 视频 + 文本结合分析

json

{"prompt": "分析该参考视频的镜头节奏、卖点表达与可复刻的分镜结构", "imageUrls": ["https://example.com/reference.mp4"], "model": "GEM_3_1_PRO", "thinkingLevel": "low"}

4. 快速翻译

json

{"prompt": "Translate to German: 'Wireless Bluetooth Speaker with LED Light'", "imageUrls": [], "model": "GEM_3_FLASH", "thinkingLevel": "low"}

1. Basic Text Generation

json

{"prompt": "Write a compelling product description for a wireless bluetooth speaker, highlighting portability and sound quality", "imageUrls": [], "thinkingLevel": "minimal"}

2. Combined Image + Text Analysis

json

{"prompt": "Analyze the composition and selling point expression of this product main image", "imageUrls": ["https://example.com/product-main.jpg"], "model": "GEM_3_1_PRO", "thinkingLevel": "high"}

3. Combined Video + Text Analysis

json

{"prompt": "Analyze the shot rhythm, selling point expression and replicable shot structure of this reference video", "imageUrls": ["https://example.com/reference.mp4"], "model": "GEM_3_1_PRO", "thinkingLevel": "low"}

4. Fast Translation

json

{"prompt": "Translate to German: 'Wireless Bluetooth Speaker with LED Light'", "imageUrls": [], "model": "GEM_3_FLASH", "thinkingLevel": "low"}

展示规则

Display Rules

直接展示生成的文本内容。

Directly display the generated text content.

限制

Limitations

提示词最大 10 万字符。
```
imageUrls
```
最多 10 个 URL；视频分析通常只传 1 个视频 URL，不建议与图片 URL 混传。
```
GEM_3_1_PRO
```
不支持
```
minimal
```
思考等级。
失败时最多重试 3 次。

Maximum 100,000 characters for prompts.
Maximum 10 URLs in
```
imageUrls
```
; usually only pass 1 video URL for video analysis, and it is not recommended to mix with image URLs.
```
GEM_3_1_PRO
```
does not support
```
minimal
```
thinking level.
Maximum 3 retries on failure.

适用与不适用

Applicable and Inapplicable Scenarios

适用：

商品文案/标题/五点描述生成
图片内容分析和描述
文本翻译
数据分析总结
视频分析

不适用：

图片生成 →
```
linkfox-aigc-imagegen
```
视频生成 →
```
linkfox-aigc-videogen
```
报告格式输出 →
```
linkfox-report-generator
```

Applicable:

Product copy/title/five-point description generation
Image content analysis and description
Text translation
Data analysis summary
Video analysis

Inapplicable:

Image generation →
```
linkfox-aigc-imagegen
```
Video generation →
```
linkfox-aigc-videogen
```
Report format output →
```
linkfox-report-generator
```

反馈

Feedback

参见

references/api.md

。

Refer to

references/api.md