Guides API v1
VeyraAI API 开发者文档
从创建 API Key 到接收生成结果，按照当前任务查找接口、请求示例、计费规则和排查方法。
本文内容
从最贴近的目标开始，直接进入对应说明。
快速开始
用四步完成第一个文生图任务。
- 1创建 API Key
登录控制台，在 API Key 页创建测试密钥。
- 2确认模型与费用
先在能力调试页选择模型、规格和数量，确认预计费用。
- 3提交任务
使用 Bearer Token 调用对应能力的 start 接口。
- 4保存 task_id
提交成功后保存 task_id，用于查询状态、接收回调和排查问题。
cURL · 文生图
curl -X POST 'https://YOUR_API_HOST/api/v1/userText2Image/start' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "first-image-task",
"prompt": "电影感的夜晚霓虹街道",
"model": "AC API",
"resolution": "1080P",
"aspect_ratio": "9:16",
"count": 1
}'将 YOUR_API_HOST 替换为当前环境域名，YOUR_API_KEY 替换为控制台创建的密钥。
鉴权方式
所有生成接口都需要在请求头中携带 Bearer Token。
安全要求Authorization: Bearer YOUR_API_KEY
API Key 仅保存在服务端，不要写入前端代码、公开仓库或普通业务日志。测试和生产环境应使用不同密钥。
能力接口
选择能力后，可直接进入调试页验证参数与费用。
任务状态
生成任务异步执行。提交成功后保存 task_id，并持续查询直到进入终态。
queued已排队任务等待可用资源。
processing处理中模型正在生成内容。
最终结果
completed已完成读取结果和实际计费信息。
failed失败读取错误信息，本次费用为 0。
Webhook 接入
生产环境优先使用回调接收最终结果，避免高频轮询。
- 回调接口收到请求后快速返回 2xx。
- 使用 task_id 作为幂等键，避免重复处理同一结果。
- 先验证请求签名，再读取结果地址和计费信息。
- 保留回调日志，用于失败重试和问题排查。
计费口径
调试页预估与最终结算使用同一份对外计费配置。
提交前查看预计费用
按选定规格、数量或时长计算；余额不足时返回 402。
执行中等待最终结果
queued 和 processing 均不是最终扣费结果。
完成后按结果结算
completed 产生费用；failed 或服务异常费用为 0。
- 图片生成
档位单价 × 成功生成数量- 视频 / 音频
档位秒价 × 成功输出时长- 组织价格
标准费用 × 组织倍率
失败任务不扣费任务失败、服务异常或没有成功产出时，本次费用为 0。
常见错误
记录 HTTP 状态码、task_id 和响应错误信息，再按建议处理。
| 状态码 | 含义 | 处理建议 |
|---|---|---|
400 | 参数校验失败 | 核对必填字段、模型和规格组合。 |
401 | 鉴权失败 | 检查 Bearer Token 是否缺失、过期或已禁用。 |
402 | 余额不足 | 充值后重新提交任务。 |
429 | 请求过于频繁 | 降低并发并采用指数退避重试。 |
500 | 服务异常 | 保留请求信息和 task_id，稍后重试；失败任务不扣费。 |
仍未定位问题？
联系技术支持联系支持时请附上请求时间、能力类型、状态码和 task_id。
没有找到相关文档
换一个关键词，或搜索“鉴权”“task_id”“计费”“错误码”。