> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socialvision.tisyk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Ideogram 3.0 接口参考

> Ideogram 文生图、图片编辑、Remix 重制与背景替换

## 图像描述

`POST /ideogram/describe`

分析图片并生成文字描述（反向提示词）。请求体为 `multipart/form-data`。

官方文档：[https://developer.ideogram.ai/api-reference/api-reference/describe](https://developer.ideogram.ai/api-reference/api-reference/describe)

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/describe" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "created_at": 1733851336696,
    "task_id": "CjMT7WdSwWcAAAAAALvB3g",
    "task_status": "submitted",
    "updated_at": 1733851336696
  },
  "message": "SUCCEED",
  "request_id": "CjMT7WdSwWcAAAAAALvB3g"
}
```

***

## 文生图

`POST /ideogram/generate`

根据文本提示词生成图像（Ideogram V2 API）。

Generates images synchronously based on a given prompt and optional parameters.
具体参数请看官方文档：[https://developer.ideogram.ai/api-reference/api-reference/describe](https://developer.ideogram.ai/api-reference/api-reference/describe)

根据给定的提示和可选参数同步生成图像。
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片

### 请求体参数 (Body)

<ParamField body="image_request" type="object" required>
  图像请求对象 (必填)
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "image_request": {
    "aspect_ratio": "ASPECT_1_1",
    "color_palette": {
      "name": "PASTEL"
    },
    "magic_prompt_option": "AUTO",
    "model": "V_2",
    "negative_prompt": "",
    "num_images": 1,
    "prompt": "A minimalist logo design for a coffee shop",
    "resolution": "1024x1024",
    "seed": 1785282233,
    "style_type": "DESIGN"
  }
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/generate" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image_request": {
    "aspect_ratio": "ASPECT_1_1",
    "color_palette": {
      "name": "PASTEL"
    },
    "magic_prompt_option": "AUTO",
    "model": "V_2",
    "negative_prompt": "",
    "num_images": 1,
    "prompt": "A minimalist logo design for a coffee shop",
    "resolution": "1024x1024",
    "seed": 1785282233,
    "style_type": "DESIGN"
  }
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "created": "2024-12-15T17:32:00.965408Z",
  "data": [
    {
      "is_image_safe": true,
      "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
      "resolution": "768x1232",
      "seed": 1785282233,
      "url": "https://ideogram.ai/api/images/ephemeral/WkoxvqiOTaaCqG1nO2tQoA.png?exp=1734370337&sig=110fe96dc9e01002c8d837e5b4cde1aaa266195561d231ce76e19e095e478ffe"
    }
  ]
}
```

***

## 图像 Remix

`POST /ideogram/remix`

基于已有图像和提示词生成变体。请求体为 `multipart/form-data`，需上传图片文件。

官方文档：[https://developer.ideogram.ai/api-reference/api-reference/remix](https://developer.ideogram.ai/api-reference/api-reference/remix)

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/remix" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "created_at": 1733851336696,
    "task_id": "CjMT7WdSwWcAAAAAALvB3g",
    "task_status": "submitted",
    "updated_at": 1733851336696
  },
  "message": "SUCCEED",
  "request_id": "CjMT7WdSwWcAAAAAALvB3g"
}
```

***

## 图像放大

`POST /ideogram/upscale`

对已有图像进行高清放大。请求体为 `multipart/form-data`。

官方文档：[https://developer.ideogram.ai/api-reference/api-reference/upscale](https://developer.ideogram.ai/api-reference/api-reference/upscale)

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/upscale" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "created_at": 1733851336696,
    "task_id": "CjMT7WdSwWcAAAAAALvB3g",
    "task_status": "submitted",
    "updated_at": 1733851336696
  },
  "message": "SUCCEED",
  "request_id": "CjMT7WdSwWcAAAAAALvB3g"
}
```

***

## Generate 3.0（图片编辑）Edit

`POST /ideogram/v1/ideogram-v3/edit`

使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像
具体参数请看官方文档：[https://developer.ideogram.ai/api-reference/api-reference/edit-v3](https://developer.ideogram.ai/api-reference/api-reference/edit-v3)
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片

### 请求体参数 (Body)

<ParamField body="image" type="string" required>
  图像正在重新处理（最大大小为 10 兆字节）；目前仅支持 JPEG、WebP 和 PNG 格式。
</ParamField>

<ParamField body="mask" type="string">
  蒙版图片（编辑区域）
</ParamField>

<ParamField body="prompt" type="string">
  文本提示词
</ParamField>

<ParamField body="seed" type="integer">
  随机种子，范围0-2147483647，设置此值可获得可重复的结果
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/v1/ideogram-v3/edit" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "created_at": 1733851336696,
    "task_id": "CjMT7WdSwWcAAAAAALvB3g",
    "task_status": "submitted",
    "updated_at": 1733851336696
  },
  "message": "SUCCEED",
  "request_id": "CjMT7WdSwWcAAAAAALvB3g"
}
```

***

## Generate 3.0（文生图）Generate

`POST /ideogram/v1/ideogram-v3/generate`

使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像
具体参数请看官方文档：[https://developer.ideogram.ai/api-reference/api-reference/generate-v3](https://developer.ideogram.ai/api-reference/api-reference/generate-v3)
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片

Ideogram 3.0 文生图（JSON 模式参考）。

### 请求参数 (Query / Path)

<ParamField header="Content-Type" type="string" required>
  请求体 Content-Type，一般为 application/json
</ParamField>

<ParamField header="Accept" type="string" required>
  期望的响应 Content-Type
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API Key
</ParamField>

### 请求体参数 (Body)

<ParamField body="aspect_ratio" type="string">
  用于图像生成的纵横比，决定图像的分辨率。不能与resolution参数同时使用。默认为1x1
</ParamField>

<ParamField body="color_palette" type="object">
  生成的颜色调色板，必须通过预设之一（name）或通过带有可选权重的颜色的十六进制表示（members）明确指定
</ParamField>

<ParamField body="magic_prompt" type="string">
  决定是否在生成请求时使用Magic Prompt
</ParamField>

<ParamField body="negative_prompt" type="string">
  描述要在图像中排除的内容。提示中的描述优先于负面提示中的描述
</ParamField>

<ParamField body="num_images" type="integer">
  要生成的图像数量
</ParamField>

<ParamField body="prompt" type="string" required>
  生成图像所需的提示文本
</ParamField>

<ParamField body="rendering_speed" type="string">
  渲染速度选项
</ParamField>

<ParamField body="resolution" type="string">
  支持的分辨率选项
</ParamField>

<ParamField body="seed" type="integer">
  随机种子。设置此值可获得可重复的生成结果
</ParamField>

<ParamField body="style_codes" type="array">
  表示图像风格的8字符十六进制代码列表。不能与style\_reference\_images或style\_type一起使用
</ParamField>

<ParamField body="style_type" type="string">
  要生成的风格类型
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "prompt": "voluptate reprehenderit",
  "rendering_speed": "DEFAULT",
  "seed": 511526458
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/v1/ideogram-v3/generate" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "voluptate reprehenderit",
  "rendering_speed": "DEFAULT",
  "seed": 511526458
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "created": "2025-08-27T18:23:28.806107195+08:00",
  "data": [
    {
      "is_image_safe": true,
      "prompt": "voluptate reprehenderit",
      "resolution": "1024x1024",
      "seed": 511526458,
      "style_type": "REALISTIC",
      "url": "https://v3.fal.media/files/koala/mSnuEvKTrnyY2mXY1i_qc_image.png"
    }
  ]
}
```

***

## Generate 3.0（图片重构）Reframe

`POST /ideogram/v1/ideogram-v3/reframe`

使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像
具体参数请看官方文档：[https://developer.ideogram.ai/api-reference/api-reference/reframe-v3](https://developer.ideogram.ai/api-reference/api-reference/reframe-v3)
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片

### 请求参数 (Query / Path)

<ParamField header="Accept" type="string" required>
  期望的响应 Content-Type
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API Key
</ParamField>

### 请求体参数 (Body)

<ParamField body="image" type="string" required>
  图像正在重新处理（最大大小为 10 兆字节）；目前仅支持 JPEG、WebP 和 PNG 格式。
</ParamField>

<ParamField body="resolution" type="string">
  分辨率，如 720p、1080p
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/v1/ideogram-v3/reframe" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "created_at": 1733851336696,
    "task_id": "CjMT7WdSwWcAAAAAALvB3g",
    "task_status": "submitted",
    "updated_at": 1733851336696
  },
  "message": "SUCCEED",
  "request_id": "CjMT7WdSwWcAAAAAALvB3g"
}
```

***

## Generate 3.0（图片重制）Remix

`POST /ideogram/v1/ideogram-v3/remix`

使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像
具体参数请看官方文档：[https://developer.ideogram.ai/api-reference/api-reference/remix-v3](https://developer.ideogram.ai/api-reference/api-reference/remix-v3)
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片

### 请求参数 (Query / Path)

<ParamField header="Accept" type="string" required>
  期望的响应 Content-Type
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API Key
</ParamField>

### 请求体参数 (Body)

<ParamField body="image" type="string" required>
  图像正在重新处理（最大大小为 10 兆字节）；目前仅支持 JPEG、WebP 和 PNG 格式。
</ParamField>

<ParamField body="num_images" type="string">
  生成图片数量
</ParamField>

<ParamField body="prompt" type="string">
  文本提示词
</ParamField>

<ParamField body="rendering_speed" type="string">
  渲染速度档位
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/v1/ideogram-v3/remix" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "created": "2025-08-27T22:13:44.972624193+08:00",
  "data": [
    {
      "is_image_safe": true,
      "prompt": "A photo of a cat",
      "resolution": "1024x1024",
      "seed": 12345,
      "style_type": "REALISTIC",
      "url": "https://v3.fal.media/files/panda/-6uzsYt1XEco4s6BThKaP_image.png"
    }
  ]
}
```

***

## Generate 3.0（替换背景） Replace Background

`POST /ideogram/v1/ideogram-v3/replace-background`

使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像
具体参数请看官方文档：[https://developer.ideogram.ai/api-reference/api-reference/replace-background-v3](https://developer.ideogram.ai/api-reference/api-reference/replace-background-v3)
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片

### 请求参数 (Query / Path)

<ParamField header="Accept" type="string" required>
  期望的响应 Content-Type
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API Key
</ParamField>

### 请求体参数 (Body)

<ParamField body="image" type="string" required>
  图像正在重新处理（最大大小为 10 兆字节）；目前仅支持 JPEG、WebP 和 PNG 格式。
</ParamField>

<ParamField body="prompt" type="string">
  文本提示词
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/ideogram/v1/ideogram-v3/replace-background" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "created_at": 1733851336696,
    "task_id": "CjMT7WdSwWcAAAAAALvB3g",
    "task_status": "submitted",
    "updated_at": 1733851336696
  },
  "message": "SUCCEED",
  "request_id": "CjMT7WdSwWcAAAAAALvB3g"
}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.