# 19 请求、响应、数据示例与错误码

听文视频工作台 · 技术架构与实现 · 1.0.2

## 创建本机照片任务

{
  "title": "6G 通信",
  "title_secondary": "产业协同与应用路径",
  "text": "这是用于解释接口契约的合成朗读示例。",
  "voice": "zh-CN-YunjianNeural",
  "image_mode": "upload",
  "photos": [
    {"photo_name": "example.png", "photo_data": "<有效PNG字节的Base64，非data URI>"}
  ]
}

成功201返回job_view。试用版应先调用trial/photos取得photo_receipt并附加；已到期即使凭据有效也不能创建。photos数组为新多图契约，也兼容单图顶层photo_data/photo_name。所有图片在活动任务创建前校验，不因半批成功就启动任务。

## URL／AI任务差异字段

{
  "text": "用于演示URL任务的正文",
  "image_mode": "url",
  "photo_url": "https://example.org/example.png"
}

上面example.org是说明占位，不执行下载。URL模式不需prompt/Key。AI模式使用以下差异字段，Key必须真实由用户提供，不应写在文档、日志或源码中：

{
  "text": "用于演示AI任务的正文",
  "image_mode": "generate",
  "provider": "seedream",
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "横向构图的科技城市，蓝色光线，主体明确",
  "api_key": "<由用户在运行时填写，不作为文档凭据>",
  "payment_consent": true
}

## 素材筛选与确认

// POST /api/jobs/<id>/select-images
{"image_version": "<当前版本>", "selected_indices": [0, 2]}

// POST /api/jobs/<id>/confirm
{"image_version": "<筛选后的当前版本>"}

索引必须真实int、合法、非重复、非空；筛选仍按原图库顺序保存，不能当任意排序API。全选不改变版本；有变化会更新版本并清确认。confirm使用最新版本，不提交客户端自造摘要，SHA256由后端计算。

## 通用草稿字段

{
  "title": "示例",
  "titleSecondary": "副标题",
  "text": "朗读正文",
  "prompt": "图片要求",
  "voice": "zh-CN-YunxiNeural",
  "imageMode": "upload",
  "provider": "seedream",
  "selectedId": ""
}

注意草稿字段titleSecondary/imageMode为前端驼峰，任务title_secondary/image_mode为后端下划线。GET缺失/不可读草稿返回{}，POST成功为{"ok":true}；非法音色回默认、非法imageMode回upload、provider固定seedream、selectedId非法UUID回空。试用草稿保存会再次经过统一计数，不能绕过账本。

## 试用usage实际合成样例

下面样例来自独立临时目录中的Flask test_client调用，不包含个人内容，没有发起在线合成或收费请求。输入字符串“中😀，空格换行”用转义JSON表达实际5个码点，同文再次发送不增加。

// POST /api/mobile/trial/text
{"text": "中😀， \n"}

// HTTP 200
{
  "expired": false,
  "max_photos": 10,
  "max_text_characters": 10000,
  "photos_remaining": 10,
  "photos_used": 0,
  "text_remaining": 9995,
  "text_used": 5,
  "wechat": "wzqy2019"
}

trial-status额外有completed；trial/photos额外有photo_receipt；migration_note是可选说明。恰好10000字或10张HTTP200但expired=true，后续制作HTTP400。text非string如{"text":1}返回400“文案格式无效”；trial/photos仅upload模式，url不接受。

{
  "error": "试用已到期：累计输入最多 10000 字（含标点、空格和换行）或累计选择 10 张照片；获取正式版请联系微信：wzqy2019"
}

## HTTP结果分类

状态码 | 
主要含义 | 
处理建议 | 

200 | 
状态/读取/动作接受 | 
仍需检查job状态或expired，不把200当制作一定成功 | 

201 | 
新任务已建立 | 
继续轮询素材步骤 | 

400 | 
格式、参数、标题、图片或试用到期 | 
显示error，按原因处理 | 

403 | 
Android密钥、Host、Origin或本机会话不合法 | 
仅明确过期拒绝可恢复一次会话 | 

404 | 
未知任务、动作、媒体或文件 | 
不试图扩大路径范围 | 

409 | 
活动冲突、未就绪、素材版本变化、未知付费重发未确认 | 
等处理结束或重新预览/明确决定 | 

413 | 
超64MiB请求体 | 
压缩或减少照片 | 

415 | 
非JSON POST | 
使用正确内容类型；可能为Flask默认HTML错误，不保证统一JSON | 

500/其他异常 | 
未被业务捕获的服务错误或环境故障 | 
保留输入/素材，检查诊断，不自动重发收费动作 | 

注册的400/403/404/409/413通常返回{"error":...}；会话拒绝另有code。不是所有HTTP异常均有统一结构，文档/客户端应保留非JSON失败分支。

---
招商合作微信：wzqy2019。添加备注：听文合作。
原网页：https://tingwen-creator-studio-102.pages.dev/guide/technical-19