# Recraft V4.1 Flash — Scenepond API

模型 ID: `recraft/v4.1/flash/text-to-image`

模型开发者: Recraft

用途: 文生图

原始页面: https://open.scenepond.ai/zh/models/recraft%2Fv4.1%2Fflash%2Ftext-to-image#api

核对日期: 2026-10-01

API 地址: `https://scenepond-api-production.up.railway.app/v1`

每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。

## 原生任务 API

`POST /v1/tasks/fal`

### 最小调用

#### cURL

```bash
curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/tasks/fal" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "recraft/v4.1/flash/text-to-image",
  "prompt": "A quiet lakeside at sunrise"
}
JSON
```

#### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

payload = json.loads("{\n  \"model\": \"recraft/v4.1/flash/text-to-image\",\n  \"prompt\": \"A quiet lakeside at sunrise\"\n}")

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/fal",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

#### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/fal", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "recraft/v4.1/flash/text-to-image",
  "prompt": "A quiet lakeside at sunrise"
})
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 请求参数

- `model` — **必填**; `string`. 使用此处显示的完整公开模型 ID。
  - 约束: `const = "recraft/v4.1/flash/text-to-image"`

- `prompt` — **必填**; `string`. 描述主体、场景和期望生成的内容。
  - 约束: `maxLength = 10000`; `minLength = 1`

- `image_size` — **可选**; `string`. 选择输出尺寸预设。此网关不接受自定义宽高对象。
  - 默认: `"square_hd"`
  - 约束: `enum = ["square_hd","square","portrait_4_3","portrait_16_9","landscape_4_3","landscape_16_9"]`

- `background_color` — **可选**; `object`. 期望的背景颜色，使用红、绿、蓝分量表示。

### background_color 中的字段

仅在提供 background_color 时适用；子字段必填不代表可选的父字段也必填。

- `background_color.g` — **可选**; `integer`. 绿色分量。
  - 默认: `0`
  - 约束: `maximum = 255`; `minimum = 0`

- `background_color.b` — **可选**; `integer`. 蓝色分量。
  - 默认: `0`
  - 约束: `maximum = 255`; `minimum = 0`

- `background_color.r` — **可选**; `integer`. 红色分量。
  - 默认: `0`
  - 约束: `maximum = 255`; `minimum = 0`


- `enable_safety_checker` — **可选**; `boolean`. 是否启用上游安全检查；上游政策可能禁止关闭此选项。
  - 默认: `true`

- `colors` — **可选**; `array<object>`. 期望的配色；数组中的每一项均为红、绿、蓝颜色对象。
  - 默认: `[]`

### colors 中的字段

仅在提供 colors 时适用；子字段必填不代表可选的父字段也必填。

- `colors[].g` — **可选**; `integer`. 绿色分量。
  - 默认: `0`
  - 约束: `maximum = 255`; `minimum = 0`

- `colors[].b` — **可选**; `integer`. 蓝色分量。
  - 默认: `0`
  - 约束: `maximum = 255`; `minimum = 0`

- `colors[].r` — **可选**; `integer`. 红色分量。
  - 默认: `0`
  - 约束: `maximum = 255`; `minimum = 0`


- `size` — **可选**; `string`. image_size 或 resolution 的别名。建议使用本表准确的原生值；像素尺寸别名可能不匹配区分大小写的分辨率值。

- `parameters` — **可选**; `object`. 本表原生参数的另一种容器写法；同一设置不可重复填写不同值。

- `metadata` — **可选**; `object`. 另一种容器写法：将原生参数放在 metadata.parameters 内。

### 响应示例

响应示例仅展示结构；ID、URL 和数值为占位内容。

#### 提交响应

```json
{
  "id": "task_EXAMPLE",
  "task_id": "task_EXAMPLE",
  "status": "queued",
  "model": "recraft/v4.1/flash/text-to-image",
  "created_at": 1700000000
}
```

#### 已完成任务的状态

```json
{
  "task_id": "task_EXAMPLE",
  "platform": "fal",
  "status": "SUCCESS",
  "progress": "100%",
  "fail_reason": "",
  "created_at": 1700000000,
  "finished_at": 1700000060
}
```

#### 生成文件列表

```json
{
  "task_id": "task_EXAMPLE",
  "artifacts": [
    {
      "key": "image-1",
      "type": "image",
      "content_url": "https://scenepond-api-production.up.railway.app/v1/tasks/task_EXAMPLE/artifacts/image-1/content"
    }
  ]
}
```

### 后续请求

#### 2. 查询任务状态

将 SCENEPOND_TASK_ID 设为返回的 task_id，每隔几秒查询，直到 SUCCESS 或 FAILURE。状态中包含进度和 fail_reason，但不包含生成文件。

##### cURL

```bash
curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

#### 3. 获取生成结果

SUCCESS 后查询生成文件列表，使用返回的 content_url 和认证信息下载。请妥善保管带签名的地址。

##### cURL

```bash
curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID/artifacts" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "/artifacts",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "/artifacts", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 调用注意事项

- 每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。
- 参数值区分大小写。未填写或为 null 时，存在默认值的设置使用默认值；有效的 0 和 false 会被保留。
- 参数表使用 JSON 顶层的原生字段名，也可放入 parameters 或 metadata.parameters。未知的嵌套字段和重复参数中的冲突值会被拒绝。
- 提交后返回排队任务。先轮询状态，再在 SUCCESS 后查询生成文件列表。
- POST 超时后不要自动重新提交。保存已返回的任务 ID，先检查状态，再决定是否创建新的付费任务。
- 默认值和限制依据当前网关与关联的上游参数规范；上游或网关更新后可能变化。

## 资料来源

- [上游模型参数规范](https://fal.ai/models/fal-ai/recraft/v4.1/flash/text-to-image/api)