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

创建本机照片任务

{
  "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结果分类

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