CRUD 与更新接口¶

本页列出当前 ORPC SDK 暴露的写入、更新、删除和资料管理接口。高层方法会尽量把返回值转换成 SDK 模型；如果后端返回结构不匹配，会原样返回 dict / list。

字段命名

create_*() 和 update_*() 的额外字段通过 **fields 直接传给后端 ORPC。Python 方法使用 snake_case，命名空间同时保留部分后端一致的 camelCase 别名。

调用风格¶

from aimage.search.client import SearchClient
from aimage.search.settings import SearchService

with SearchClient(service=SearchService.DEV) as client:
    project = client.get_project("project_id")
    print(project)

同一个接口通常有三种入口：

# Python 友好的方法
client.update_clip_subtitle("clip_id", "new subtitle")

# 对齐后端 router 的 namespace
client.kensaku.clips.updateSubtitle("clip_id", "new subtitle")

# 原始 ORPC
client.rpc("kensaku/clips/updateSubtitle", {
    "clip_id": "clip_id",
    "subtitle": "new subtitle",
})

项目设置与功能开关¶

项目设置接口位于 kensaku/projects/updateSettings。

用途	Python 方法	Namespace
获取项目	`get_project(project_id)`	`client.kensaku.projects.get(project_id)`
更新 agent 模型或功能开关	`update_project_settings(project_id, agent_model=..., feature_flags=...)`	`client.kensaku.projects.updateSettings(project_id, ...)`
设置功能开关	`set_project_feature_flags(project_id, ...)`	—
设置功能开关别名	`enable_project_features(project_id, ...)`	—

client.update_project_settings(
    "project_id",
    agent_model="gpt-4.1",
    feature_flags={
        "translationTable": True,
        "materialReading": True,
    },
)

client.set_project_feature_flags(
    "project_id",
    image_generation=True,
    translation_table=True,
    material_reading=True,
    clip_embedding_search=True,
)

Project 实例也提供同等方法：

project.update_settings(agent_model="gpt-4.1")
project.set_feature_flags(translation_table=True)

当前 SDK 包装的功能开关为：

Python 参数	后端字段
`image_generation`	`imageGeneration`
`translation_table`	`translationTable`
`material_reading`	`materialReading`
`clip_embedding_search`	`clipEmbeddingSearch`

角色与角色资料¶

角色接口位于 data/characters/*，支持角色本体、图库、概念图、设定和材料绑定。

用途	Python 方法	Namespace
列表	`list_characters(project_id, q=None)`	`client.data.characters.list(project_id, q=...)`
获取	`get_character(character_id)`	`client.data.characters.get(character_id)`
创建	`create_character(project_id, **fields)`	`client.data.characters.create(project_id, **fields)`
更新	`update_character(character_id, **fields)`	`client.data.characters.update(character_id, **fields)`
删除	`delete_character(character_id)`	`client.data.characters.delete(character_id)`
添加图库图	`add_character_gallery_image(character_id, file_path)`	原始 ORPC
批量添加图库图	`add_character_gallery_images(character_id, file_paths)`	原始 ORPC
移除图库图	`remove_character_gallery_image(character_id, index)`	原始 ORPC
添加概念图	`add_character_concept_art(character_id, file_path)`	原始 ORPC
批量添加概念图	`add_character_concept_art_batch(character_id, file_paths)`	原始 ORPC
移除概念图	`remove_character_concept_art(character_id, index)`	原始 ORPC
列出角色设定	`list_character_settings(character_id)`	原始 ORPC
创建角色设定	`create_character_setting(character_id, **fields)`	原始 ORPC
更新角色设定	`update_character_setting(setting_id, **fields)`	原始 ORPC
删除角色设定	`delete_character_setting(setting_id)`	原始 ORPC
绑定材料到设定	`assign_character_materials_to_setting(character_id, setting_id, file_paths)`	原始 ORPC
取消材料绑定	`unassign_character_materials_from_settings(character_id, file_paths)`	原始 ORPC

character = client.create_character(
    "project_id",
    name="司",
    name_en="Tsukasa",
    name_alias=["つかさ"],
    features=["blue eyes"],
    description="main character",
)

client.update_character(
    character.id,
    is_pinned=True,
    features=["blue eyes", "school uniform"],
)

client.add_character_gallery_image(character.id, "characters/tsukasa/main.png")
client.add_character_concept_art_batch(
    character.id,
    ["characters/tsukasa/concept-1.png", "characters/tsukasa/concept-2.png"],
)

setting = client.create_character_setting(character.id, name="School uniform")
client.assign_character_materials_to_setting(
    character.id,
    setting["id"],
    ["materials/uniform-front.png"],
)

Project 实例可直接创建角色：

project.create_character(name="司", name_en="Tsukasa")

资源与其他材料¶

Resource 是项目级文件资料，适合保存剧本、设定资料、其他材料、翻译表源文件等。接口位于 data/resources/*。

用途	Python 方法	Namespace
列表	`list_resources(project_id, **filters)`	`client.data.resources.list(project_id, **filters)`
获取	`get_resource(resource_id)`	`client.data.resources.get(resource_id)`
创建	`create_resource(project_id, **fields)`	`client.data.resources.create(project_id, **fields)`
更新	`update_resource(resource_id, **fields)`	`client.data.resources.update(resource_id, **fields)`
删除	`delete_resource(resource_id)`	`client.data.resources.delete(resource_id)`
批量获取上传 URL	`batch_presigned_resource_urls(project_id, files)`	原始 ORPC
文件夹路径	`resource_folder_paths(project_id)`	原始 ORPC
启动材料 OCR	`start_material_ocr(project_id, resource_id, **fields)`	原始 ORPC
查询 OCR 进度	`material_ocr_progress(progress_id)`	原始 ORPC

resource = client.create_resource(
    "project_id",
    name="Character setting sheet",
    description="Main cast reference",
    file_path="materials/characters.pdf",
    file_type="resources",
    folder_path="materials",
)

client.update_resource(resource.id, description="Updated notes")

progress = client.start_material_ocr("project_id", resource.id, language="ja")
client.material_ocr_progress(progress["progress_id"])

Project 实例提供便捷方法：

for resource in project.resources(file_type="resources"):
    print(resource)

project.create_resource(name="notes.md", file_path="materials/notes.md")

参考图像¶

参考图像接口位于 data/referenceImages/*。

用途	Python 方法	Namespace
列表	`list_reference_images(project_id, page=1, size=300, **filters)`	`client.data.referenceImages.list(project_id, **filters)`
搜索	`search_reference_images(project_id, page=1, size=40, **filters)`	`client.data.referenceImages.search(project_id, **filters)`
标签选项	`reference_image_tag_options(project_id, **filters)`	`client.data.referenceImages.tag_options(project_id, **filters)`
获取	`get_reference_image(reference_image_id)`	`client.data.referenceImages.get(reference_image_id)`
创建	`create_reference_image(project_id, **fields)`	`client.data.referenceImages.create(project_id, **fields)`
更新	`update_reference_image(reference_image_id, **fields)`	`client.data.referenceImages.update(reference_image_id, **fields)`
删除	`delete_reference_image(reference_image_id)`	`client.data.referenceImages.delete(reference_image_id)`

reference = client.create_reference_image(
    "project_id",
    resource_id="resource_id",
    category="background_art",
    tags=["school", "day"],
    purpose="classroom background",
    license="licensed",
    is_searchable=True,
)

client.update_reference_image(reference.id, tags=["school", "day", "interior"])

ReferenceImage 支持 save(path) 和 save_bytes() 下载文件。

翻译表¶

翻译表接口位于 data/translationTables/*，条目接口位于 data/translationTables/entries/*。

用途	Python 方法	Namespace
表列表	`list_translation_tables(project_id, page=1, size=300, **filters)`	`client.data.translationTables.list(project_id, **filters)`
获取表	`get_translation_table(table_id)`	`client.data.translationTables.get(table_id)`
创建表	`create_translation_table(project_id, **fields)`	`client.data.translationTables.create(project_id, **fields)`
更新表	`update_translation_table(table_id, **fields)`	`client.data.translationTables.update(table_id, **fields)`
删除表	`delete_translation_table(table_id)`	`client.data.translationTables.delete(table_id)`
条目列表	`list_translation_table_entries(table_id, page=1, size=300, **filters)`	`client.data.translationTables.entries.list(table_id, **filters)`
创建条目	`create_translation_table_entry(table_id, raw_values, **fields)`	`client.data.translationTables.entries.create(table_id, raw_values, **fields)`
更新条目	`update_translation_table_entry(entry_id, **fields)`	`client.data.translationTables.entries.update(entry_id, **fields)`
删除条目	`delete_translation_table_entry(entry_id)`	`client.data.translationTables.entries.delete(entry_id)`

table = client.create_translation_table(
    "project_id",
    name="Character names",
    description="JA / EN / ZH names",
    columns=[
        {"key": "ja", "label": "日本語", "index": 0},
        {"key": "en", "label": "English", "index": 1},
        {"key": "zh", "label": "中文", "index": 2},
    ],
)

entry = client.create_translation_table_entry(
    table.id,
    raw_values={"ja": "司", "en": "Tsukasa", "zh": "司"},
)

client.update_translation_table_entry(
    entry.id,
    raw_values={"ja": "司", "en": "Tsukasa", "zh": "司"},
)

Project 实例也支持：

for table in project.translation_tables(q="Character"):
    print(table)

project.create_translation_table(
    name="Terms",
    columns=[
        {"key": "ja", "label": "日本語", "index": 0},
        {"key": "en", "label": "English", "index": 1},
    ],
)

漫画与小说资料¶

漫画接口位于 data/mangas/*，小说接口位于 data/novels/*。

用途	漫画方法	小说方法
列表	`list_mangas(project_id, **filters)`	`list_novels(project_id, **filters)`
获取	`get_manga(meta_id)`	`get_novel(meta_id)`
创建	`create_manga(project_id, **fields)`	`create_novel(project_id, **fields)`
更新	`update_manga(meta_id, **fields)`	`update_novel(meta_id, **fields)`
删除	`delete_manga(meta_id)`	`delete_novel(meta_id)`
处理任务	`get_manga_processing(processing_id)` / `find_manga_processing_by_meta(meta_id)`	`get_novel_processing(processing_id)` / `find_novel_processing_by_meta(meta_id)`

小说还支持检索和段落上下文：

results = client.query_novels(
    "project_id",
    "confession scene",
    k=5,
    content_type="dialogue",
)

context = client.get_novel_segment_context(
    "project_id",
    "segment_id",
    context_radius=2,
)

Clip Metadata、标签、角色和字幕¶

Clip 接口位于 kensaku/clips/*。

用途	Python 方法	Namespace
获取	`get_clip(clip_id)`	`client.kensaku.clips.get(clip_id)`
获取详情	`get_clip_detail(clip_id)`	`client.kensaku.clips.getDetail(clip_id)`
按集列出	`list_episode_clips(project_id, episode_number, ...)`	`client.kensaku.clips.episodeClips(project_id, episode_number, ...)`
文本搜索	`text_search_clips(project_id, query, **fields)`	`client.kensaku.clips.textSearch(project_id, query, **fields)`
多模态搜索	`multimodal_search_clips(project_id, **fields)`	`client.kensaku.clips.multimodalSearch(project_id, **fields)`
更新 Clip	`update_clip(clip_id, **fields)`	`client.kensaku.clips.update(clip_id, **fields)`
更新标签	`update_clip_tags(clip_id, tags, **fields)`	`client.kensaku.clips.updateTags(clip_id, tags)`
更新角色	`update_clip_characters(clip_id, character_ids)`	`client.kensaku.clips.updateCharacters(clip_id, character_ids)`
更新字幕	`update_clip_subtitle(clip_id, subtitle)`	`client.kensaku.clips.updateSubtitle(clip_id, subtitle)`

clip = client.get_clip_detail("clip_id")

client.update_clip(
    clip.id,
    description="A wide classroom shot",
    metadata={
        "scene_type": "NORMAL",
        "location": "classroom",
        "characters": ["Tsukasa"],
    },
)

client.update_clip_tags(
    clip.id,
    {
        "camera_work": "FIX",
        "object_size": "LONG_SHOT",
        "location": "classroom",
    },
)

client.update_clip_characters(clip.id, ["character_id"])
client.update_clip_subtitle(clip.id, "I remember this place.")

Clip 实例也能原地更新自身：

clip.update_subtitle("I remember this place.")
clip.update_characters(["character_id"])
clip.update_tags({"dialog_sentiment": "POSITIVE"})
clip.update(metadata={"notes": "checked by editor"})

Agent 读写与对话分支¶

Agent 接口位于 agent/read/* 和 agent/write/*。对话接口位于 kensaku/chatbot/conversations/*。

用途	Python 方法	Namespace
读取项目上下文	`agent_read_project_context(project_id)`	`client.agent.read.projectContext(project_id)`
读取标签选项	`agent_read_tag_options(project_id)`	`client.agent.read.tagOptions(project_id)`
读取角色	`agent_read_characters(project_id)`	`client.agent.read.characters(project_id)`
读取对话历史	`agent_read_conversation_history(conversation_id, **fields)`	`client.agent.read.conversationHistory(conversation_id, **fields)`
搜索 clips	`agent_search_clips(project_id, query, **fields)`	`client.agent.read.searchClips(project_id, query, **fields)`
搜索 novels	`agent_search_novels(project_id, query, **fields)`	`client.agent.read.searchNovels(project_id, query, **fields)`
补全 clips	`agent_hydrate_clips(clip_ids)`	`client.agent.read.hydrateClips(clip_ids)`
预览视觉资产	`agent_visual_asset_preview(project_id, visual_asset_id)`	`client.agent.read.visualAssetPreview(project_id, visual_asset_id)`
保存生成图	`agent_save_generated_image(project_id, visual_asset_id, **fields)`	`client.agent.write.saveGeneratedImage(project_id, visual_asset_id, **fields)`
列出对话	`list_conversations(**filters)`	`client.kensaku.chatbot.conversations.list(**filters)`
创建对话	`create_conversation(project_id, title="新対話")`	`client.kensaku.chatbot.conversations.create(project_id, title)`
获取对话	`get_conversation(conversation_id)`	`client.kensaku.chatbot.conversations.get(conversation_id)`
添加消息	`add_conversation_message(conversation_id, message, **fields)`	`client.kensaku.chatbot.conversations.addMessage(conversation_id, message, **fields)`
编辑消息	`edit_conversation_message(conversation_id, message_id, content, **fields)`	`client.kensaku.chatbot.conversations.editMessage(conversation_id, message_id, content, **fields)`
切换分支	`switch_conversation_branch(conversation_id, message_id=None, branch_id=None)`	`client.kensaku.chatbot.conversations.switchBranch(conversation_id, message_id=...)`

context = client.agent.read.projectContext("project_id")
clips = client.agent.read.searchClips("project_id", "school hallway", limit=5)

conversation = client.create_conversation("project_id", title="Scene search")
message = client.add_conversation_message(conversation["id"], "Find school hallway cuts")

# 分支切换可传 message_id；SDK 也接受 branch_id 作为兼容别名。
client.switch_conversation_branch(conversation["id"], message_id=message["id"])