{"openapi":"3.0.3","info":{"title":"Qora 视频 API","version":"1.7.0","description":"本站视频API格式，与网页/画布共用积分与方案。不代表任意OpenAI兼容软件可直接使用。完整文档：https://qorastudio.cn/developers"},"servers":[{"url":"https://qorastudio.cn"}],"tags":[{"name":"账户","description":"本站账户可用积分"},{"name":"模型","description":"模型编号、价格、规格和可用状态"},{"name":"素材","description":"上传本账号参考文件"},{"name":"视频","description":"报价、生成、查询与下载"},{"name":"任务日志","description":"近7天任务分页、进度、失败原因与详情"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Qora API Key"}},"schemas":{"AccountBalance":{"type":"object","additionalProperties":false,"required":["balance_credits","balance_cny","currency","credits_per_cny","updated_at"],"properties":{"balance_credits":{"type":"number","minimum":0,"description":"本账号当前可用积分，与网站钱包一致"},"balance_cny":{"type":"number","minimum":0,"description":"按10积分=1元折算的本站服务计价金额"},"currency":{"type":"string","enum":["CNY"]},"credits_per_cny":{"type":"number","enum":[10]},"updated_at":{"type":"integer","format":"int64","description":"钱包最近变动时间，不是本次查询时间；没有记录时为null","nullable":true}}},"BalanceEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AccountBalance"}}},"VideoRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"images":{"type":"array","minItems":1,"maxItems":10,"description":"兼容旧接法，仅qr-v042支持的公网HTTPS图片直链数组，含OSS签名链接；取图速度受外部图源影响。新接入推荐 /api/v1/assets/direct 直传并确认后填写references。每图最多30MB，PNG/JPEG/WebP。与非空references互斥；task_mode可省略，自动使用references。地址须持续有效且不依赖Cookie/Referer或跳转。","items":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"}},"max_price_credits":{"type":"number","minimum":0,"maximum":1000000,"description":"可接受的最高总积分；报价超过此上限不提交、不扣分。需要参考视频费用确认的方案还必须显式提供本字段"},"prompt":{"type":"string","maxLength":16000,"description":"普通方案须非空；模型prompt_required=false时可传空字符串，仍需此字段"},"route_id":{"type":"string","minLength":1,"maxLength":80,"default":"qr-v007","description":"GET /api/v1/video/models返回的id；须available=true"},"duration":{"type":"integer","minimum":1,"maximum":30,"default":4,"description":"须同时符合模型durations与所选清晰度duration_ranges"},"resolution":{"type":"string","enum":["480p","768p","720p","1080p","1088p","1440p","4k"],"default":"480p"},"ratio":{"type":"string","enum":["21:9","16:9","4:3","1:1","3:4","9:16"],"default":"16:9"},"task_mode":{"type":"string","enum":["text","first_frame","first_last_frame","references"],"default":"text"},"references":{"type":"array","maxItems":50,"description":"推荐先调用 /api/v1/assets/direct 取得授权，将文件直传本站OSS并complete确认status=ready，使用返回id。仅使用本账号上传返回的素材ID；实际数量、角色和组合按模型限制。Seedance全能参考按图片、视频、音频分组，每类独立从1编号，对应prompt中的@图1、@视频1、@音频1；仅写@不会上传文件。中文可紧邻引用；紧邻数字或英文字母时请加空格或括号，例如@图5（203宿舍）；超出已添加数量的引用会在生成前返回具体编号与行号，不会自动猜测图片。","items":{"$ref":"#/components/schemas/Reference"}}}},"Reference":{"type":"object","additionalProperties":false,"required":["id","role"],"properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["reference_image","reference_video","reference_audio","first_frame","last_frame"]}}},"VideoJob":{"type":"object","additionalProperties":false,"required":["id","model","status","progress","price_credits","duration","resolution","ratio","uploaded_at","expired","created_at","completed_at","expires_at","error","download_url"],"properties":{"id":{"type":"string","format":"uuid"},"model":{"type":"string","description":"本站方案ID，对应route_id"},"status":{"type":"string","enum":["estimating","quoted","queued","preparing","dispatching","submitted","polling","downloading","delivery_blocked","uncertain","completed","failed","expired","cancelled"]},"progress":{"type":"number","nullable":true,"minimum":0,"maximum":100},"price_credits":{"type":"number","minimum":0,"description":"整条任务售价，单位积分，以本次有效报价为准"},"price_breakdown":{"type":"object","properties":{"output_seconds":{"type":"integer"},"reference_video_seconds":{"type":"number"},"reference_billable_seconds":{"type":"integer"},"output_credits":{"type":"number"},"reference_credits":{"type":"number"},"total_credits":{"type":"number"}}},"pricing":{"type":"object","description":"骨折官方480p按输出时长计费的单价与秒数","properties":{"unit_credits_per_second":{"type":"number"},"output_seconds":{"type":"integer"},"billing_basis":{"type":"string","enum":["output_duration"]}}},"duration":{"type":"integer"},"resolution":{"type":"string"},"ratio":{"type":"string"},"uploaded_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expired":{"type":"boolean"},"created_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒"},"completed_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"error":{"type":"object","nullable":true,"required":["code","message"],"properties":{"reference_errors":{"type":"array","maxItems":40,"description":"仅列出能与本站已提交素材准确对应的问题项；index从1开始按素材类型编号","items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["image","video","audio"]},"index":{"type":"integer","minimum":1,"maximum":30},"reference_id":{"type":"string","format":"uuid","description":"本账号素材ID"},"reason_code":{"type":"string"},"message":{"type":"string"},"suggestion":{"type":"string"}}}},"reason_code":{"type":"string","description":"本站稳定原因分类，不是原始服务错误码"},"suggestion":{"type":"string","description":"按已确认原因给出的处理建议"},"specific":{"type":"boolean","description":"false表示没有可确认的具体失败原因"},"problem_id":{"type":"string","description":"本站问题编号，联系客服核查时提供"},"code":{"type":"string"},"message":{"type":"string"}}},"download_url":{"type":"string","nullable":true,"description":"新生成的视频返回 OSS 公网直链，无需 Bearer；旧文件的本站相对路径仍需鉴权"}}},"VideoQuote":{"type":"object","additionalProperties":false,"required":["id","model","status","progress","price_credits","duration","resolution","ratio","uploaded_at","expired","created_at","completed_at","expires_at","error","download_url","quote_ready","quote_expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"model":{"type":"string","description":"本站方案ID，对应route_id"},"status":{"type":"string","enum":["estimating","quoted","queued","preparing","dispatching","submitted","polling","downloading","delivery_blocked","uncertain","completed","failed","expired","cancelled"]},"progress":{"type":"number","nullable":true,"minimum":0,"maximum":100},"price_credits":{"type":"number","minimum":0,"description":"整条任务售价，单位积分，以本次有效报价为准"},"price_breakdown":{"type":"object","properties":{"output_seconds":{"type":"integer"},"reference_video_seconds":{"type":"number"},"reference_billable_seconds":{"type":"integer"},"output_credits":{"type":"number"},"reference_credits":{"type":"number"},"total_credits":{"type":"number"}}},"pricing":{"type":"object","description":"骨折官方480p按输出时长计费的单价与秒数","properties":{"unit_credits_per_second":{"type":"number"},"output_seconds":{"type":"integer"},"billing_basis":{"type":"string","enum":["output_duration"]}}},"duration":{"type":"integer"},"resolution":{"type":"string"},"ratio":{"type":"string"},"uploaded_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expired":{"type":"boolean"},"created_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒"},"completed_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"error":{"type":"object","nullable":true,"required":["code","message"],"properties":{"reference_errors":{"type":"array","maxItems":40,"description":"仅列出能与本站已提交素材准确对应的问题项；index从1开始按素材类型编号","items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["image","video","audio"]},"index":{"type":"integer","minimum":1,"maximum":30},"reference_id":{"type":"string","format":"uuid","description":"本账号素材ID"},"reason_code":{"type":"string"},"message":{"type":"string"},"suggestion":{"type":"string"}}}},"reason_code":{"type":"string","description":"本站稳定原因分类，不是原始服务错误码"},"suggestion":{"type":"string","description":"按已确认原因给出的处理建议"},"specific":{"type":"boolean","description":"false表示没有可确认的具体失败原因"},"problem_id":{"type":"string","description":"本站问题编号，联系客服核查时提供"},"code":{"type":"string"},"message":{"type":"string"}}},"download_url":{"type":"string","nullable":true,"description":"新生成的视频返回 OSS 公网直链，无需 Bearer；旧文件的本站相对路径仍需鉴权"},"quote_ready":{"type":"boolean","description":"仅报价就绪时为true；不是生成完成标记"},"quote_expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒"},"retry_after_seconds":{"type":"integer","minimum":1,"description":"报价尚未就绪时，等待此秒数后用相同订单和参数重试；尚未扣积分"}}},"QuoteEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VideoQuote"}}},"JobEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VideoJob"}}},"JobList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":300,"items":{"$ref":"#/components/schemas/VideoJob"}}}},"Asset":{"type":"object","additionalProperties":false,"required":["id","type"],"properties":{"uploaded_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expired":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["image/png","image/jpeg","image/webp","video/mp4","video/webm","audio/mpeg","audio/wav"]}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"reason_code":{"type":"string"},"suggestion":{"type":"string"},"specific":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}}}}},"VideoModel":{"type":"object","required":["id","model","name","available","note","billing","prices_credits","resolutions","ratios","durations","duration_ranges","modes","references","prompt_required","prompt_limit","duration_source"],"properties":{"material_requirements":{"type":"object","description":"本站当前方案检查要求，字节为单位；image_geometry.scope=site_compatibility表示本站兼容检查，并非其他方案通用限制","properties":{"file_bytes":{"type":"object","properties":{"image":{"type":"integer","minimum":0},"video":{"type":"integer","minimum":0},"audio":{"type":"integer","minimum":0}}},"total_bytes":{"type":"integer","nullable":true},"total_count":{"type":"integer","nullable":true},"reference_video_total_seconds":{"type":"number","description":"可选，参考视频总时长上限；H3长视频为15秒"},"reference_audio_total_seconds":{"type":"number","description":"可选，本站参考音频合计兼容上限；H3长视频为15秒"},"formats":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"image_geometry":{"type":"object","nullable":true,"properties":{"min":{"type":"number"},"max":{"type":"number"},"scope":{"type":"string","enum":["site_compatibility","model_requirement"]},"min_edge":{"type":"integer"},"max_edge":{"type":"integer"},"allow_alpha":{"type":"boolean"}}}}},"reference_video_prices_credits":{"type":"object","additionalProperties":{"type":"number"},"description":"历史按秒方案的参考视频单价，每秒积分"},"reference_video_max_seconds":{"type":"number"},"output_and_reference_max_seconds":{"type":"number"},"reference_video_rounding":{"type":"string","enum":["ceil_total_seconds"]},"id":{"type":"string"},"model":{"type":"string"},"name":{"type":"string"},"available":{"type":"boolean"},"note":{"type":"string"},"billing":{"type":"string","enum":["second","generation"]},"prices_credits":{"type":"object","additionalProperties":{"type":"number","minimum":0},"description":"按清晰度列出积分单价；1元=10积分"},"prices_credits_with_reference_video":{"type":"object","additionalProperties":{"type":"number","minimum":0},"description":"含参考视频时按成片秒数使用的积分单价；骨折官方480p为2.2，与无参考视频同价"},"reference_video_billing":{"type":"string","enum":["output_duration"]},"price_credits_per_generation":{"type":"number","minimum":0,"description":"可选的固定按条标价，单位积分"},"specifications_pending":{"type":"boolean","description":"有规格待确认，暂不开放调用"},"resolutions":{"type":"array","items":{"type":"string"}},"ratios":{"type":"array","items":{"type":"string"}},"durations":{"type":"array","items":{"type":"integer"}},"duration_ranges":{"type":"object","nullable":true,"additionalProperties":{"type":"object","required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}},"modes":{"type":"array","items":{"type":"string","enum":["text","first_frame","first_last_frame","references"]}},"references":{"type":"object","required":["images","videos","audio","min_images","min_audio"],"properties":{"images":{"type":"integer","minimum":0},"videos":{"type":"integer","minimum":0},"audio":{"type":"integer","minimum":0},"min_images":{"type":"integer","minimum":0},"min_audio":{"type":"integer","minimum":0},"audio_max_total_seconds":{"type":"number","minimum":0,"description":"可选，参考音频总时长上限，单位秒；原生720为15"},"audio_requires_image":{"type":"boolean","description":"可选，传参考音频时须搭配图片"}}},"prompt_required":{"type":"boolean"},"prompt_limit":{"type":"integer","nullable":true,"description":"待确认方案为null，且available=false"},"duration_source":{"type":"string","enum":["duration","audio_duration"]}}},"ModelList":{"type":"object","required":["data","currency","credits_per_cny"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoModel"}},"currency":{"type":"string","enum":["credits"]},"credits_per_cny":{"type":"number","enum":[10]}}},"TaskLogItem":{"type":"object","properties":{"expired":{"type":"boolean"},"api_key":{"type":"object","nullable":true,"description":"只返回本账号密钥名称和脱敏标识；旧任务未记录密钥时为null","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hint":{"type":"string"}}},"kind":{"type":"string","enum":["video","image"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"提示词摘要"},"model":{"type":"string","description":"本站展示编号；视频为qr-v，图片为qr-i"},"model_name":{"type":"string"},"source":{"type":"string","enum":["studio","canvas","api","web","admin","unknown"]},"status":{"type":"string","enum":["queued","processing","completed","failed","reviewing","delivery_blocked","cancelled"]},"stage":{"type":"string"},"stage_name":{"type":"string"},"progress":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"已报告的阶段进度；未提供时为null，不能据此判断成功"},"created_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"started_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳","nullable":true},"finished_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳","nullable":true},"updated_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"elapsed_ms":{"type":"integer","nullable":true,"minimum":0,"description":"包含排队、生成和文件接收；进行中任务按当前时间计算"},"duration":{"type":"integer","nullable":true},"resolution":{"type":"string"},"ratio":{"type":"string"},"price_credits":{"type":"number"},"charged_credits":{"type":"number","description":"实际扣除积分"},"refunded_credits":{"type":"number","description":"已确认退回的积分"},"net_credits":{"type":"number"},"uploaded_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳","nullable":true},"expires_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳","nullable":true},"file_status":{"type":"string","enum":["ready","expired","missing","manual","pending"]},"content_url":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"media_type":{"type":"string","nullable":true},"error":{"type":"object","nullable":true,"properties":{"reference_errors":{"type":"array","maxItems":40,"description":"仅列出能与本站已提交素材准确对应的问题项；index从1开始按素材类型编号","items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["image","video","audio"]},"index":{"type":"integer","minimum":1,"maximum":30},"reference_id":{"type":"string","format":"uuid","description":"本账号素材ID"},"reason_code":{"type":"string"},"message":{"type":"string"},"suggestion":{"type":"string"}}}},"reason_code":{"type":"string","description":"本站原因分类"},"problem_id":{"type":"string","description":"本站问题编号"},"code":{"type":"string","description":"本站错误分类"},"message":{"type":"string","description":"可向用户展示的原因"},"suggestion":{"type":"string","description":"处理建议"},"specific":{"type":"boolean","description":"false代表现有记录未提供具体原因"}}},"reuse":{"type":"object","properties":{"available":{"type":"boolean"},"expiresAt":{"type":"integer","format":"int64","description":"Unix毫秒时间戳","nullable":true},"reason":{"type":"string"}}}}},"TaskLogDetail":{"allOf":[{"$ref":"#/components/schemas/TaskLogItem"},{"type":"object","properties":{"prompt":{"type":"string"},"parameters":{"type":"object","properties":{"duration":{"type":"integer","nullable":true},"resolution":{"type":"string"},"ratio":{"type":"string"},"mode":{"type":"string"},"reference_counts":{"type":"object","properties":{"images":{"type":"integer"},"videos":{"type":"integer"},"audio":{"type":"integer"}}}}},"timeline":{"type":"array","items":{"type":"object","properties":{"stage":{"type":"string"},"name":{"type":"string"},"at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"}}}},"timing_note":{"type":"string"}}}]},"TaskLogPage":{"type":"object","required":["data","page","page_size","total","pages","has_more","as_of","window","generated_at"],"properties":{"data":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/TaskLogItem"}},"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"},"has_more":{"type":"boolean"},"as_of":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"generated_at":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"window":{"type":"object","properties":{"from":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"to":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"days":{"type":"integer","enum":[7]},"timezone":{"type":"string","enum":["Asia/Shanghai"]}}}}}}},"paths":{"/api/v1/tasks/usage":{"get":{"operationId":"getApiTaskUsage","tags":["任务日志"],"summary":"本账号近7天API任务用量与积分","security":[{"bearerAuth":[]}],"parameters":[{"name":"key_id","in":"query","required":false,"schema":{"type":"string"},"description":"本账号密钥UUID；unattributed表示未记录密钥"},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"本站模型编号"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","queued","processing","completed","failed","reviewing","delivery_blocked","cancelled","expired"]},"description":"任务状态"},{"name":"id","in":"query","required":false,"schema":{"type":"string"},"description":"本站任务编号"},{"name":"from","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"提交时间下限，最多近7天"},{"name":"to","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"提交时间上限"},{"name":"as_of","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"固定本轮查询时间"}],"description":"仅统计API提交任务，支持按密钥筛选。扣除、退回、净消耗均依据本站钱包流水；不包含其他账号数据。","responses":{"200":{"description":"用量汇总","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"processing":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"cancelled":{"type":"integer"},"success_rate":{"type":"number","nullable":true,"description":"成功数÷(成功数+失败数)，未结束和取消任务不计入分母；无已结束任务为null"},"success_rate_denominator":{"type":"integer"},"success_rate_note":{"type":"string"},"charged_credits":{"type":"number"},"refunded_credits":{"type":"number"},"net_credits":{"type":"number"},"as_of":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"window":{"type":"object"}}}}}},"400":{"description":"查询参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"需要本账号API密钥","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"任务不存在、超过近7天范围或不属于本账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁，降低频率后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"暂时无法读取任务记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/tasks/export":{"get":{"operationId":"exportApiTaskUsage","tags":["任务日志"],"summary":"导出本账号API任务对账CSV","security":[{"bearerAuth":[]}],"parameters":[{"name":"key_id","in":"query","required":false,"schema":{"type":"string"},"description":"本账号密钥UUID；unattributed表示未记录密钥"},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"本站模型编号"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","queued","processing","completed","failed","reviewing","delivery_blocked","cancelled","expired"]},"description":"任务状态"},{"name":"id","in":"query","required":false,"schema":{"type":"string"},"description":"本站任务编号"},{"name":"from","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"提交时间下限，最多近7天"},{"name":"to","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"提交时间上限"},{"name":"as_of","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"固定本轮查询时间"}],"description":"沿用用量筛选与统计范围。服务端每批100条，按需流式输出，密钥仅展示名称和脱敏标识；输出包含扣分、已退积分及净消耗。","responses":{"200":{"description":"UTF-8 CSV，含BOM；取消下载会停止后续批次读取","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"查询参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"需要本账号API密钥","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"任务不存在、超过近7天范围或不属于本账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁，降低频率后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"暂时无法读取任务记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/tasks":{"get":{"operationId":"listTaskHistory","tags":["任务日志"],"summary":"分页查询近7天本账号任务","security":[{"bearerAuth":[]}],"description":"视频与图片、网页与画布及API提交任务统一查询，不提交生成、不扣积分。默认每页25条，最多100条。图片仅开放历史查询，不代表开放图片生成API。不含仅报价未受理记录。分页时沿用返回的as_of，可排除查询开始后新增任务；超过实际7天窗口的记录仍会退出列表。","parameters":[{"name":"key_id","in":"query","required":false,"schema":{"type":"string"},"description":"本账号密钥UUID；unattributed筛选未记录密钥的历史任务"},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"本站qr-v或qr-i模型编号"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"description":"页码"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"每页条数"},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["all","video","image"],"default":"all"},"description":"类型"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","queued","processing","completed","failed","reviewing","delivery_blocked","cancelled","expired"],"default":"all"},"description":"expired筛选成片已过期的成功任务"},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["all","studio","canvas","api","web","admin","unknown"],"default":"all"},"description":"api仅筛选API提交；历史来源缺失为unknown"},{"name":"id","in":"query","required":false,"schema":{"type":"string","maxLength":36},"description":"完整本站UUID或至少前4位编号，不是订单号"},{"name":"from","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"提交时间下限，最多近7天"},{"name":"to","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"提交时间上限"},{"name":"as_of","in":"query","required":false,"schema":{"type":"integer","format":"int64","description":"Unix毫秒时间戳"},"description":"同一轮翻页沿用首次返回值"}],"responses":{"200":{"description":"分页列表；data中只包含本账号任务","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskLogPage"}}}},"400":{"description":"查询参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"需要本账号API密钥","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"任务不存在、超过近7天范围或不属于本账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁，降低频率后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"暂时无法读取任务记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/tasks/{kind}/{id}":{"parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["video","image"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getTaskHistoryDetail","tags":["任务日志"],"summary":"查询完整任务详情与可展示报错","security":[{"bearerAuth":[]}],"description":"data含完整提示词、参数、已记录的阶段时间、本站失败说明及处理建议。未记录的阶段时间为null，不推测。积分退回金额只依据实际流水。成功任务成片过期后仍可在7天内查看任务信息。","responses":{"200":{"description":"任务详情","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskLogDetail"}}}}}},"400":{"description":"查询参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"需要本账号API密钥","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"任务不存在、超过近7天范围或不属于本账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁，降低频率后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"暂时无法读取任务记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/tasks/{kind}/{id}/content":{"parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["video","image"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"downloadTaskHistoryContent","tags":["任务日志"],"summary":"下载本账号未过期的视频或图片","security":[{"bearerAuth":[]}],"description":"只在file_status=ready且download_url非空时下载。支持Range字节续传、206与307跳转到本站自有存储。中断后重试原下载地址，不重新生成。遇到200完整响应不得追加至部分文件。使用安全跟随重定向的客户端，勿将本站密钥转发到其他域名。文件保存期以expires_at为准，任务记录可查7天不代表文件保存7天。","responses":{"200":{"description":"图片或视频完整二进制"},"206":{"description":"字节范围文件；核对Content-Range和Content-Length"},"307":{"description":"临时签名下载地址"},"400":{"description":"查询参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"需要本账号API密钥","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"任务不存在、超过近7天范围或不属于本账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"成片尚未完成","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"文件保存期已结束","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"416":{"description":"字节范围无效"},"429":{"description":"请求过于频繁，降低频率后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"暂时无法读取任务记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/balance":{"get":{"operationId":"getAccountBalance","tags":["账户"],"security":[{"bearerAuth":[]}],"summary":"查询本账号可用积分","description":"Bearer密钥所属账号的可用积分与人民币计价金额，与网站钱包一致。多把密钥共享同一账号余额，不接收其他账号查询参数。查询不扣生成积分、不创建任务；建议60秒刷新一次，与其他API共用每账号每分钟60次限额。响应private,no-store。","responses":{"200":{"description":"data为本站账户余额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceEnvelope"},"example":{"data":{"balance_credits":712.5,"balance_cny":71.25,"currency":"CNY","credits_per_cny":10,"updated_at":1792324800000}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"余额暂时无法读取","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"balance_unavailable","message":"账户余额暂时无法读取，请稍后重试"}}}}}}}},"/api/v1/video/models":{"get":{"operationId":"listVideoModels","tags":["模型"],"security":[{"bearerAuth":[]}],"summary":"查询视频模型与规格","responses":{"200":{"description":"data为方案列表，包含暂停展示方案；available=true才可调用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}},"/api/v1/assets/direct":{"post":{"operationId":"directUploadAsset","tags":["素材"],"security":[{"bearerAuth":[]}],"summary":"推荐：OSS直传授权与确认，返回生成用的素材编号","description":"文件正文直接POST到响应host的本站自有OSS；Qora只接收元信息和确认请求。本站Bearer密钥仅用于此控制接口，不能转发到host。确认status=ready后才可用于生成。重复授权或确认不延长素材有效期、不扣生成积分。","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["action","source","size","type"],"properties":{"action":{"type":"string","enum":["authorize"]},"source":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"原始文件内容SHA-256"},"size":{"type":"integer","minimum":1,"maximum":104857600},"type":{"type":"string","enum":["image/png","image/jpeg","image/webp","video/mp4","video/webm","audio/mpeg","audio/wav"]}}},{"type":"object","additionalProperties":false,"required":["action","id"],"properties":{"action":{"type":"string","enum":["complete"]},"id":{"type":"string","format":"uuid","description":"授权返回的本站素材编号"}}}]}}}},"responses":{"200":{"description":"单文件上传授权，或已核验素材","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["id","status","upload_mode","host","fields","authorization_expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["uploading"]},"upload_mode":{"type":"string","enum":["post_form"]},"host":{"type":"string","format":"uri"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"所有字段原样作为multipart表单字段；file放最后"},"authorization_expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒"}}},{"type":"object","required":["id","status","type","uploaded_at","expires_at","expired"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["ready"]},"type":{"type":"string"},"uploaded_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expired":{"type":"boolean"}}}]}}}},"400":{"description":"参数或请求格式错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_request","message":"参数无效，请按模型列表中的规格填写"}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"404":{"description":"素材不存在或不属于当前账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"文件未传完或仍有原上传连接，请保留素材编号并按Retry-After重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"保存期已结束，需重新上传","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"超过存储入口文件大小或控制请求大小","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"文件大小、格式或完整SHA-256不匹配","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}},"/api/v1/assets":{"get":{"operationId":"getAssetStatus","tags":["素材"],"summary":"批量查询本账号素材可用状态及到期时间","security":[{"bearerAuth":[]}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"1至50个本站素材UUID，以逗号分隔"}],"responses":{"200":{"description":"素材元数据；不存在或他人素材统一返回missing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","maxItems":50,"items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ready","pending","expired","missing"]},"size":{"type":"integer","nullable":true},"type":{"type":"string","nullable":true},"uploaded_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expires_at":{"type":"integer","format":"int64","description":"Unix时间戳，单位毫秒","nullable":true},"expired":{"type":"boolean"}}}}}}}}},"400":{"description":"参数或请求格式错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_request","message":"参数无效，请按模型列表中的规格填写"}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"402":{"description":"积分余额不足，未进入生成队列","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"积分余额不足，请先兑换卡密"}}}}},"409":{"description":"方案不可用、订单冲突或报价未就绪","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"idempotency_conflict","message":"生成未完成，请稍后重试"}}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}},"post":{"operationId":"uploadAsset","tags":["素材"],"security":[{"bearerAuth":[]}],"summary":"兼容旧接法：二进制上传参考素材","description":"新接入推荐先使用 /api/v1/assets/direct 直传本站OSS并确认，再用素材id填写references。本入口不是multipart。PNG/JPEG/WebP和MP4/WebM单文件最多100MiB；MP3/WAV最多20MiB。每账号最多500个素材、5GiB空间，模型要求可能更严格。同账号相同摘要复用原素材。","parameters":[{"name":"X-Qora-Source","in":"header","required":true,"description":"本文件内容SHA-256，小写十六进制","schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}},{"name":"Content-Length","in":"header","required":true,"description":"文件字节数，通常由客户端自动设置","schema":{"type":"integer","minimum":1,"maximum":104857600}}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"本账号已有相同文件","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"},"example":{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","type":"image/png"}}}},"201":{"description":"新素材已保存","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"},"example":{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","type":"image/png"}}}},"400":{"description":"参数或请求格式错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_request","message":"参数无效，请按模型列表中的规格填写"}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"409":{"description":"方案不可用、订单冲突或报价未就绪","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"idempotency_conflict","message":"生成未完成，请稍后重试"}}}}},"411":{"description":"缺少有效Content-Length","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"文件或保存空间超限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}},"/api/v1/video/quotes":{"post":{"operationId":"quoteVideoGeneration","tags":["视频"],"security":[{"bearerAuth":[]}],"summary":"查询本次报价，不提交生成、不扣积分","description":"可选步骤，可不调用此接口而直接提交生成。JSON体与生成接口相同。报价最长有效60秒。返回data包装，quote_ready=true才代表已就绪。","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"同账号同订单同参数重试复用原任务；改变参数返回409；新任务才使用新订单号","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"},"examples":{"directAsset25":{"summary":"推荐：OSS直传确认后使用本站素材编号","value":{"route_id":"qr-v042","prompt":"参考图1作为人物参考，镜头平稳推进。","duration":30,"resolution":"720p","ratio":"16:9","task_mode":"references","references":[{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","role":"reference_image"}]}},"ossImages25":{"summary":"兼容旧接法：公网图片链接，速度受图源影响","value":{"route_id":"qr-v042","prompt":"参考图1作为人物参考，镜头平稳推进。","duration":30,"resolution":"720p","ratio":"16:9","images":["https://your-bucket.oss-cn-hongkong.aliyuncs.com/reference.png"]}},"stable25":{"summary":"稳定版480p：0.35元/秒","value":{"route_id":"qr-v007","prompt":"纸船缓缓漂过水面，镜头保持平稳。","duration":4,"resolution":"480p","ratio":"16:9","task_mode":"text"}},"tenImage25":{"summary":"满血10图：720p每条55积分、1080p每条70积分","value":{"route_id":"qr-v042","prompt":"镜头平稳掠过海面。","duration":30,"resolution":"720p","ratio":"16:9","task_mode":"text"}},"wan":{"summary":"万相3.0：每条25积分，参考视频不另收费","value":{"route_id":"qr-v043","prompt":"参考@视频1的动作节奏，镜头平稳推进。","duration":10,"resolution":"720p","ratio":"16:9","task_mode":"references","references":[{"id":"cccccccc-cccc-4ccc-8ccc-cccccccccccc","role":"reference_video"}]}},"mini":{"summary":"Mini按条：每条15积分","value":{"route_id":"qr-v021","prompt":"参考图中的小船缓缓驶过石桥，水面自然泛起涟漪。","duration":15,"resolution":"720p","ratio":"16:9","task_mode":"references","references":[{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","role":"reference_image"}]}},"multimodal":{"summary":"稳定版全能参考：先核对完整报价","value":{"route_id":"qr-v007","prompt":"人物参考@图1，动作参考@视频1，声音参考@音频1。人物面向镜头自然说话。","duration":4,"resolution":"480p","ratio":"16:9","task_mode":"references","references":[{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","role":"reference_image"},{"id":"cccccccc-cccc-4ccc-8ccc-cccccccccccc","role":"reference_video"},{"id":"dddddddd-dddd-4ddd-8ddd-dddddddddddd","role":"reference_audio"}]}}}}}},"responses":{"200":{"description":"报价草稿；HTTP200不保证quote_ready为true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteEnvelope"},"example":{"data":{"id":"aaaaaaaa-aaaa-5aaa-8aaa-aaaaaaaaaaaa","model":"qr-v021","status":"quoted","progress":null,"price_credits":15,"duration":15,"resolution":"720p","ratio":"16:9","created_at":1792324800000,"completed_at":null,"expires_at":null,"error":null,"download_url":null,"quote_ready":true,"quote_expires_at":1792324860000}}}}},"400":{"description":"参数或请求格式错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_request","message":"参数无效，请按模型列表中的规格填写"}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"402":{"description":"积分余额不足，未进入生成队列","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"积分余额不足，请先兑换卡密"}}}}},"409":{"description":"方案不可用、订单冲突或报价未就绪","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"idempotency_conflict","message":"生成未完成，请稍后重试"}}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}},"/api/v1/video/generations":{"post":{"operationId":"createVideoGeneration","tags":["视频"],"security":[{"bearerAuth":[]}],"summary":"提交视频生成任务","description":"无需先调用报价接口；服务端仍会核价和检查积分。直接返回任务对象，无data包装。queued才表示已入队并预扣积分；estimating/quoted尚未入队。同订单同参数重试复用原任务，不会重新生成已经完成或失败的任务。JSON体最多64000字节。","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"同账号同订单同参数重试复用原任务；改变参数返回409；新任务才使用新订单号","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"},"examples":{"directAsset25":{"summary":"推荐：OSS直传确认后使用本站素材编号","value":{"route_id":"qr-v042","prompt":"参考图1作为人物参考，镜头平稳推进。","duration":30,"resolution":"720p","ratio":"16:9","task_mode":"references","references":[{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","role":"reference_image"}]}},"ossImages25":{"summary":"兼容旧接法：公网图片链接，速度受图源影响","value":{"route_id":"qr-v042","prompt":"参考图1作为人物参考，镜头平稳推进。","duration":30,"resolution":"720p","ratio":"16:9","images":["https://your-bucket.oss-cn-hongkong.aliyuncs.com/reference.png"]}},"stable25":{"summary":"稳定版480p：0.35元/秒","value":{"route_id":"qr-v007","prompt":"纸船缓缓漂过水面，镜头保持平稳。","duration":4,"resolution":"480p","ratio":"16:9","task_mode":"text"}},"tenImage25":{"summary":"满血10图：720p每条55积分、1080p每条70积分","value":{"route_id":"qr-v042","prompt":"镜头平稳掠过海面。","duration":30,"resolution":"720p","ratio":"16:9","task_mode":"text"}},"wan":{"summary":"万相3.0：每条25积分，参考视频不另收费","value":{"route_id":"qr-v043","prompt":"参考@视频1的动作节奏，镜头平稳推进。","duration":10,"resolution":"720p","ratio":"16:9","task_mode":"references","references":[{"id":"cccccccc-cccc-4ccc-8ccc-cccccccccccc","role":"reference_video"}]}},"mini":{"summary":"Mini按条：每条15积分","value":{"route_id":"qr-v021","prompt":"参考图中的小船缓缓驶过石桥，水面自然泛起涟漪。","duration":15,"resolution":"720p","ratio":"16:9","task_mode":"references","references":[{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","role":"reference_image"}]}},"multimodal":{"summary":"稳定版全能参考：先核对完整报价","value":{"route_id":"qr-v007","prompt":"人物参考@图1，动作参考@视频1，声音参考@音频1。人物面向镜头自然说话。","duration":4,"resolution":"480p","ratio":"16:9","task_mode":"references","references":[{"id":"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb","role":"reference_image"},{"id":"cccccccc-cccc-4ccc-8ccc-cccccccccccc","role":"reference_video"},{"id":"dddddddd-dddd-4ddd-8ddd-dddddddddddd","role":"reference_audio"}]}}}}}},"responses":{"202":{"description":"返回当前任务；202不等于视频生成完成","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoJob"},"example":{"id":"aaaaaaaa-aaaa-5aaa-8aaa-aaaaaaaaaaaa","model":"qr-v021","status":"queued","progress":null,"price_credits":15,"duration":15,"resolution":"720p","ratio":"16:9","created_at":1792324800000,"completed_at":null,"expires_at":null,"error":null,"download_url":null}}}},"400":{"description":"参数或请求格式错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_request","message":"参数无效，请按模型列表中的规格填写"}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"402":{"description":"积分余额不足，未进入生成队列","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"积分余额不足，请先兑换卡密"}}}}},"409":{"description":"方案不可用、订单冲突或报价未就绪","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"idempotency_conflict","message":"生成未完成，请稍后重试"}}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}},"get":{"operationId":"listVideoGenerations","tags":["视频"],"security":[{"bearerAuth":[]}],"summary":"读取本账号任务列表","description":"最多300条，无分页参数；优先进行中任务，包含报价草稿和最近历史。","responses":{"200":{"description":"data为任务数组","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"},"example":{"data":[{"id":"aaaaaaaa-aaaa-5aaa-8aaa-aaaaaaaaaaaa","model":"qr-v021","status":"queued","progress":null,"price_credits":15,"duration":15,"resolution":"720p","ratio":"16:9","created_at":1792324800000,"completed_at":null,"expires_at":null,"error":null,"download_url":null}]}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}},"/api/v1/video/generations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"本站任务UUID，不是订单号或模型ID","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getVideoGeneration","tags":["视频"],"security":[{"bearerAuth":[]}],"summary":"查询本账号任务状态","description":"建议30秒一次。completed后下载；downloading继续等待；delivery_blocked表示成片超过250MiB自动接收上限，停止轮询并联系站长单独领取，原任务保留、不自动退款、不重复生成；uncertain保留任务号核查，不要更换订单重生成。error不为空需结合status判断，可能只是临时文件整理提示。时间字段单位毫秒。","responses":{"200":{"description":"data为任务对象","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"},"example":{"data":{"id":"aaaaaaaa-aaaa-5aaa-8aaa-aaaaaaaaaaaa","model":"qr-v021","status":"completed","progress":100,"price_credits":15,"duration":15,"resolution":"720p","ratio":"16:9","created_at":1792324800000,"completed_at":1792325160000,"expires_at":1792584360000,"error":null,"download_url":"/api/v1/video/generations/aaaaaaaa-aaaa-5aaa-8aaa-aaaaaaaaaaaa/content"}}}}},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"404":{"description":"任务不存在或不属于本账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}},"/api/v1/video/generations/{id}/content":{"parameters":[{"name":"id","in":"path","required":true,"description":"本站任务UUID，不是订单号或模型ID","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"downloadVideo","tags":["视频"],"security":[{"bearerAuth":[]}],"summary":"下载本账号成品视频","parameters":[{"name":"Range","in":"header","schema":{"type":"string"},"description":"单段字节范围，例如bytes=1048576-"},{"name":"If-Range","in":"header","schema":{"type":"string"},"description":"续传时的强ETag；校验不符返回完整文件，不能追加"}],"description":"支持Range字节续传、206和307自有存储跳转。下载中断时重试原任务下载地址，勿重新生成；跨域跳转不得转发Bearer密钥。保存期以expires_at为准，新OSS成片保留72小时。请求须携带同账号Bearer密钥，普通浏览器地址栏不会自动带密钥。","responses":{"200":{"description":"按Content-Type选择mp4或webm后缀","headers":{"Content-Disposition":{"description":"成品附件文件名","schema":{"type":"string"}}},"content":{"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"字节范围文件；检查Content-Range、Content-Length和ETag"},"307":{"description":"本站自有存储临时签名地址；跨域不可转发Bearer密钥"},"401":{"description":"Key缺失、无效或撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"invalid_api_key","message":"API Key 无效或已撤销"}}}}},"404":{"description":"文件不存在或不属于当前账号","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"作品尚未完成，请继续查询原任务","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_ready","message":"作品尚未完成"}}}}},"410":{"description":"文件保存期已结束，以expires_at为准","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"content_expired","message":"视频保存期已结束，请查看已下载的文件"}}}}},"416":{"description":"请求的范围无效；Content-Range包含完整长度"},"429":{"description":"请求过频或容量繁忙；capacity_wait尚未扣积分，等待Retry-After秒后用相同Idempotency-Key和参数重试；rate_limit_exceeded表示每分钟请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"capacity_wait","message":"服务繁忙，请使用相同订单稍后重试"},"retry_after_seconds":15}}},"headers":{"Retry-After":{"description":"建议重试等待秒数；容量繁忙时返回","schema":{"type":"integer","minimum":1}}}},"503":{"description":"服务暂不可用，保留原订单或任务号重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"服务暂不可用，请稍后重试"}}}}}}}}}}