linkfox-aigc-textgen

AI テキスト生成

大規模言語モデルを使用してプロンプトに基づくテキストを生成します。画像や動画などを渡して、画像とテキストを組み合わせた理解や、動画のテキスト理解・分析にも対応しています。

主な特徴

• 2 種類のモデルから選択：高速応答（GEM_3_FLASH）と高品質な複雑な分析（GEM_3_1_PRO）。
• 画像・テキスト／動画の組み合わせ：imageUrls は画像と動画の URL に対応しています。画像は最大 10 枚、動画は通常 1 件を渡します。
• 思考の深さを制御可能：4 段階の thinkingLevel で推論の深さを制御します。
• 非同期の 2 段階呼び出し：タスク作成後、すぐに taskId を返します。クライアントはポーリングで結果を取得し、時間のかかる同期処理のタイムアウトを回避します。

モデルの説明

モデル（model）	説明	適した用途
GEM_3_FLASH	高速応答（デフォルト）	一般的な文章作成、簡単な分析、翻訳
GEM_3_1_PRO	高品質な複雑な分析	詳細な分析、長文の執筆、複雑な推論

思考レベル

thinkingLevel	説明
minimal	ほとんど思考しない（GEM_3_1_PRO は非対応）
low	思考を抑える
medium	バランス
high	最大の推論深度

パラメーターの概要

• 必須フィールド：prompt、imageUrls（画像も動画もない場合は空の配列 [] を渡します）、thinkingLevel（明示的に指定する必要があります。デフォルトは minimal を推奨します）
• メディア URL の規約：画像と動画の URL はいずれも imageUrls で渡します（動画分析の場合は ["https://example.com/ref.mp4"] のように指定します）。未文書化のフィールド（videoUrl、videoUrls など）は使用しないでください。

パラメーターの全一覧、レスポンスフィールドの構造、エラーコードについては、references/api.md を参照してください。

呼び出し方法

非同期の 2 段階方式を使用します（imagegen と同じです）。

1. タスクを作成：POST /aigc/textGenAsync → taskId を返します
2. ポーリングで結果を取得：POST /aigc/textTaskQuery → PROCESSING ／ SUCCESS ／ FAILED を返します

• Python スクリプト（タスク作成とポーリングは内部でラップされており、パラメーターの渡し方は変わりません）：
  • python scripts/aigc_textgen.py --stdin — 推奨。stdin から JSON パラメーターを読み込み、シェルのエスケープ問題を回避します（例：python scripts/aigc_textgen.py --stdin < params.json）
  • python scripts/aigc_textgen.py --stdin --content-only — content テキストのみを出力します（こちらも 1 行です）
  • python scripts/aigc_textgen.py '<JSON 参数>' [--inline] — 簡単なケースでパラメーターを直接渡します（prompt に改行が含まれる場合は使用しないでください）

ポーリング方針：1 回の HTTP タイムアウトは 150 秒です。ポーリング間隔は 10 秒から開始し、5 秒まで短縮されます。ポーリング時間は最長 600 秒です。パラメーター、レスポンス、エラーコードの詳細は references/api.md を参照してください。

改行の平坦化はデフォルトで有効です（フラグは不要）：すべての出力モードで、content の改行は自動的に 1 文字の ⏎（U+23CE）に置き換えられ、content 全体が 1 行になります。--content-only は「content テキストを出力するか、完全な JSON を出力するか」を切り替えるだけで、この平坦化の動作には影響しません。

出力の仕様（他の agent はこの仕様に従って解析してください）

• 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 全体がコンテキストに入るのを避けてください。

認証と計算リソースの問題の解決

次の問題が発生した場合は、references/onboarding.md の手順に従って解決してください。

問題が発生した場合

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• 401 または 402 のレスポンスステータス
• 計算リソースまたは残高不足を示すレスポンス：メッセージに「計算リソースの残高不足／請求額不足／残高不足／quota exceeded／insufficient balance／プランの期限切れ／チャージが必要／チャージしてください」または同様の意味の内容が含まれています。

自動連鎖呼び出しの判断ルール

Agent は以下の判断ツリーに従ってください。ルールを読んだら、ユーザーから段階ごとの指示を受けなくても自動的に実行します。

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

改行プレースホルダーの規約（コアの仕組み）

content には通常、実際の改行が含まれます。そのままシェル変数に入れたり、JSON に連結したりすると、行が分割されます。スクリプトはデフォルトで（すべてのモードで、フラグは不要）、content の改行をすべて 1 文字の ⏎（U+23CE）に置き換えます。実際の改行制御文字と、文字としての \n の両方が対象です。

• ⏎ はシェルのシングルクォート内でも JSON 文字列内でもエスケープ不要です。content 全体が 1 行になるため、変数への安全な取り込みやインライン連結が可能です。
• 下流の AIGC スクリプト（imagegen／videogen／videogen-multi）は、パラメーターの解析後に ⏎ を自動的に改行へ復元します（各 AIGC スクリプトに組み込まれた decode_nl_in_obj）。そのため、テキストを損失なく渡せます。
• content 全体が 1 行になるため、中間ファイルを使わずにシェル変数へ直接取り込み、下流のパラメーター JSON にインラインで連結できます。

標準的な 2 段階の連鎖呼び出し（imagegen／videogen／任意の AIGC Skill）

# ── Step 1：生文，--content-only 直接拿到单行 content（换行已是 ⏎），捕获进变量 ──────
PROMPT=$(python scripts/aigc_textgen.py --stdin --content-only < textgen_params.json)

# ── Step 2：内联拼接进下游参数并调用下游 Skill（jq 负责正确的 JSON 转义） ───────────
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"
# 下游脚本接收后自动把 ⏎ 还原为换行符

jq がない場合は、$PROMPT をシングルクォートの JSON に直接インラインで連結できます。⏎ はエスケープ不要で、実際の改行も含まれないため、安全に連結できます。 ただし、content に二重引用符が含まれていないことが条件です。二重引用符が含まれる場合は、jq の使用を優先してください。

各下流 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"}

使用ガイド

1. モデルの選択：簡単なタスクには GEM_3_FLASH（デフォルト、高速応答）を使用します。複雑な分析や長文の執筆には GEM_3_1_PRO を使用します。
2. プロンプト：最大 10 万文字です。説明が具体的であるほど、良い結果が得られます。
3. 画像／動画入力：imageUrls でメディア URL を渡します。テキストのみの場合は []、画像の理解には画像 1～10 枚、動画の理解には通常動画 URL（.mp4 など）を 1 件渡します。複雑な動画のショット分割や内容分析には、GEM_3_1_PRO と thinkingLevel: low の組み合わせを推奨します。
4. 思考レベル：高速応答が必要な場合は minimal／low、深い推論が必要な場合は high を選択します。
5. 動画処理に失敗した場合の代替策：動画を読み取れない、メディアにアクセスできない、10005 が返される、または内容が空の場合は、動画からフレームを抽出して画像として imageUrls に渡してください（フレーム抽出の手順は下流の業務 skill を参照してください）。

示例

1. 基础文本生成

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

2. 图片 + 文本结合分析

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

3. 视频 + 文本结合分析

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

4. 快速翻译

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

展示规则

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

限制

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

适用与不适用

适用：

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

不适用：

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

反馈

参见 references/api.md。