AI Video APIAI Video API

Ideogram V4

Ideogram V4 文生图模型，画面锐利、文字渲染业界领先，适合 Logo 设计、海报制作、营销视觉与品牌素材。

模型

模型名称输出模式
ideogram-v4图片 URL文生图

定价

按 rendering_speed 渲染速度逐张计费，所有尺寸同价：

渲染速度积分价格
TURBO16 积分$0.08
BALANCED（默认）28 积分$0.14
QUALITY44 积分$0.22

size 与 output_format 不影响价格。

创建任务

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "A minimalist coffee shop logo with the text \"Daily Brew\"",
      "size": "1:1",
      "rendering_speed": "BALANCED",
      "output_format": "png"
    }
  }'

请求体

字段类型必填说明
modelstring是固定为 ideogram-v4
inputobject是生成参数，见下表
callback_urlstring否任务完成/失败时的回调地址

Input 参数

字段类型必填说明
promptstring是描述目标图片的提示词，最长 5,000 字符
sizestring否输出尺寸预设，默认 1:1。可选：1:1、3:4、9:16、4:3、16:9
rendering_speedstring否渲染速度/质量档位，默认 BALANCED。可选：TURBO、BALANCED、QUALITY。速度越快去噪步数越少
output_formatstring否生成图片格式，默认 jpeg。可选：jpeg、png

示例：宽幅海报（TURBO）

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "input": {
      "prompt": "A retro concert poster with bold headline text \"SUMMER NIGHTS\" in neon typography",
      "size": "16:9",
      "rendering_speed": "TURBO"
    }
  }'

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "397ce9f2-c04e-4244-ac33-3af19a7cc297"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态流转：pending -> processing -> completed 或 failed。

已完成

{
  "id": "397ce9f2-c04e-4244-ac33-3af19a7cc297",
  "status": "completed",
  "model": "ideogram-v4",
  "created_at": 1781000000,
  "completed_at": 1781000020,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/images/2026/06/05/abc123.png"
    ],
    "metadata": {
      "model": "ideogram-ai/ideogram-v4"
    }
  }
}

已失败

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "ideogram-v4",
  "created_at": 1781000000,
  "error": {
    "code": "upstream_error",
    "message": "Image generation failed"
  }
}

失败任务会自动退还积分。

回调 (Callback)

创建任务时传入 callback_url，任务完成或失败时系统会自动向你的 URL 发送 POST 请求，无需轮询。

请求头

Header说明
Content-Typeapplication/json
X-Event事件类型：task.completed 或 task.failed
X-Task-Id任务 ID
X-TimestampUnix 时间戳（秒）

完成回调

{
  "id": "397ce9f2-c04e-4244-ac33-3af19a7cc297",
  "status": "completed",
  "model": "ideogram-v4",
  "created_at": 1781000000,
  "completed_at": 1781000020,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/images/2026/06/05/abc123.png"
    ],
    "metadata": {
      "model": "ideogram-ai/ideogram-v4"
    }
  }
}

失败回调

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "ideogram-v4",
  "created_at": 1781000000,
  "error": {
    "code": "upstream_error",
    "message": "Image generation failed"
  }
}

任务失败时，预扣积分会自动退还。

重试策略

如果你的服务器不可达或返回非 2xx 状态码，系统最多重试 3 次：

次数时机
第 1 次立即
第 2 次3 分钟后
第 3 次10 分钟后

3 次均失败后回调标记为 failed，你仍可通过轮询 GET /v1/tasks/{taskId} 获取最终状态。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码错误码类型说明
400invalid_requestinvalid_request_error缺少必填参数或参数无效
401invalid_api_keyauthentication_errorAPI Key 无效、已禁用或已删除
402insufficient_creditsbilling_error积分余额不足，请充值
403ip_not_allowedpermission_error请求 IP 不在 Key 的白名单中
404model_not_foundinvalid_request_error模型不存在或已停用
404task_not_foundinvalid_request_error任务 ID 不存在
429rate_limit_exceededrate_limit_error请求过于频繁，请降低频率
429spend_limit_exceededbilling_error达到 Key 的消费限额（每小时/每天/总量）
500internal_errorapi_error服务器内部错误
503upstream_errorupstream_error上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

  • Key 不以 sk- 开头
  • Key 已被禁用或删除
  • 用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

  • 输入内容包含敏感或违规信息
  • 上游服务暂时不可用
  • 请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。