genkiln

创建任务

POST /v1/tasks：提交图像或视频生成任务，包括请求字段、校验规则、计费与幂等。

HTTP
POST https://genkiln.com/v1/tasks

创建一个生成任务，并立即以 202 Accepted 返回。任务在后台执行；通过查询任务读取结果，或通过 Webhook 接收结果。

请求头

请求头必填说明
Authorization是Bearer sk_...，见鉴权。
Content-Type建议application/json。请求体始终按 JSON 解析。
Idempotency-Key否任意字符串，最长 255 个字符，用于安全重试，见幂等。

请求体

字段类型必填说明
modelstring是模型 ID，例如 veo-3.1-fast。见模型。
inputobject是模型参数。每个模型有自己的 schema：prompt、image_urls、duration、resolution、aspect_ratio 等。
callback_urlstring否公网 https 地址，任务结束后我们会 POST 任务对象到这里。见 Webhooks。
metadataobject否你自己的数据，在任务对象和 Webhook 中原样返回。最多 16 个键，JSON 后不超过 2 KB。

请求体必须是不超过 64 KB 的 JSON 对象。出现未知的顶层字段时返回 400 invalid_request，字段名在 error.param 中。

示例：图生视频 + Webhook

curl https://genkiln.com/v1/tasks \
  -H "Authorization: Bearer $GENKILN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-abc123-video" \
  -d '{
    "model": "veo-3.1-fast",
    "input": {
      "prompt": "The camera slowly pushes in as snow starts to fall",
      "image_urls": ["https://example.com/first-frame.png"],
      "duration": 8,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    },
    "callback_url": "https://your-app.com/webhooks/genkiln",
    "metadata": { "order_id": "abc123" }
  }'

参数校验

  • input 按模型 schema 校验。未传的可选字段使用默认值；未知字段会被拒绝。每个模型的参数表见模型，GET /v1/models/{id} 也会以 JSON Schema 返回。
  • 校验错误会指出字段，例如 "param": "input.duration"。
  • image_urls 中的每个 URL 以及 callback_url 必须：
    • 使用 https 和默认端口（443），URL 中不能包含用户名或密码；
    • 不超过 2,048 个字符；
    • 指向公网主机。解析到内网、回环、链路本地等非公网地址的域名会被拒绝。
  • 图片 URL 必须能被我们直接下载。无法下载或不是受支持图片格式时，任务以 invalid_input 失败（并退款）。
  • 扣费前会先检查提示词。违反可接受使用政策的提示词返回 403 content_rejected。

计费

费用由我们根据校验后的输入（含默认值）和模型的公开价目表计算，以 cost_credits 返回，并在创建任务时扣除。余额不足时返回 402 insufficient_credits，不会创建任务。

  • 按条计费的模型（Veo）：任何时长价格相同，只与分辨率有关。
  • 按秒计费的模型（Seedance、Kling）：duration × 每秒单价，单价取决于分辨率和是否生成音频。
  • 图像模型：按张计费，单价取决于分辨率。

失败、超时和被取消的任务会自动全额退款。

响应

202 Accepted，返回任务对象。新任务通常为 queued：

JSON
{
  "id": "task_01JC8ZQ0E6H2P4N7K9T3W5Y8VA",
  "object": "task",
  "model": "veo-3.1-fast",
  "status": "queued",
  "cost_credits": 390,
  "refunded": false,
  "output": null,
  "error": null,
  "created_at": "2026-11-03T08:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "metadata": { "order_id": "abc123" }
}

任务无法启动时

极少数情况下，任务已创建并扣费，但无法启动。这时我们会立即将其标记为失败并退款，返回错误而不是 202。失败的任务放在 error.task 中，方便你记录：

HTTP`error.code`含义
403content_rejected提示词或输入素材被内容安全策略拒绝。
400invalid_request输入无法处理（请检查图片 URL 和参数）。
503service_busy服务暂时繁忙。请在 Retry-After 头给出的秒数后重试。
JSON
{
  "error": {
    "code": "service_busy",
    "message": "The service is temporarily busy. Your credits have been refunded; please retry shortly.",
    "task": {
      "id": "task_01JC8ZQ0E6H2P4N7K9T3W5Y8VA",
      "status": "failed",
      "refunded": true,
      "...": "..."
    },
    "request_id": "req_01JC8ZQ0E8M3B1V6C2D4F7G9HJ"
  }
}

如果设置了 callback_url，也会收到一条 task.failed Webhook。

幂等

网络错误难免发生。为了安全重试，请发送 Idempotency-Key 请求头，值对每个逻辑任务唯一（如订单号或 UUID）。

  • 24 小时内重复使用同一个 Key，会返回原来的任务，不会再次创建或扣费。响应为 202，内容是任务的当前状态，并带有 Idempotent-Replayed: true 响应头。
  • 同一个 Key 搭配不同请求体，返回 409 idempotency_conflict。比较范围是你发送的原始 model、input、callback_url 和 metadata，重试时请发送完全相同的请求体。
  • Key 的作用域是账号（所有 API Key 共享），24 小时后可以复用。
  • 同一个 Key 的并发请求是安全的：只会创建一个任务。

错误

HTTP错误码场景
400invalid_requestJSON 无效、未知字段、校验失败、URL 不安全、metadata 过大。
401invalid_api_keyKey 缺失或无效。
402insufficient_credits余额低于任务费用。
403content_rejected提示词被内容安全策略拒绝。
404not_foundmodel 不存在。
409idempotency_conflict同一 Idempotency-Key，请求体不同。
422model_unavailable模型暂时不可用。
429rate_limited请求过多，或进行中的任务过多。见限流。

完整列表见错误。