Ideogram V3 Text to Image

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Image generation by ideogram/v3-text-to-image

Output format: WebP.

Create Task

Use this endpoint to create a new image generation task.

Get Task Details — After submission, use the unified query endpoint to check task progress and retrieve results

TIP

For production use, we recommend providing the callBackUrl parameter so your service can receive completion notifications instead of polling for task status.

Model Marketplace — Explore all available models and capabilities
Common API — Check account credits and usage

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name used for generation. This field is required. - This endpoint must use the `ideogram/v3-text-to-image` model Default：`"ideogram/v3-text-to-image"`。 Allowed values：`ideogram/v3-text-to-image`。示例：`ideogram/v3-text-to-image`。
`callBackUrl`	`string`	No	Callback URL for task completion notifications. Optional parameter. If provided, the system will send a POST request to this URL when the task completes, whether it succeeds or fails. If omitted, no callback notification will be sent. 示例：`https://your-domain.com/api/callback`。
`input`	`object`	Yes	Input parameters for the generation task.
`input.prompt`	`string`	Yes	Description of the image to generate. Maximum length: 5000 characters. 示例：A cinematic photograph of a tranquil lakeside at twilight, viewed from a slight elevation. In the center, a cluster of softly glowing reeds and water lilies emit a gentle golden light, their reflections shimmering on the calm surface. The elegant neon-style white text 'ai.modelfold.online' hovers just above the water, subtly illuminated and harmonizing with the natural glow. Surrounding willows and drifting mist frame the scene, creating a serene yet magical atmosphere, with warm highlights contrasting against the cool blues of the evening sky.。
`input.rendering_speed`	`string`	No	The rendering speed to use. - `TURBO`: Turbo - `BALANCED`: Balanced - `QUALITY`: Quality Allowed values：`TURBO` / `BALANCED` / `QUALITY`。示例：`BALANCED`。
`input.style`	`string`	No	The style type to generate with. - `AUTO`: Auto - `GENERAL`: General - `REALISTIC`: Realistic - `DESIGN`: Design Allowed values：`AUTO` / `GENERAL` / `REALISTIC` / `DESIGN`。示例：`AUTO`。
`input.expand_prompt`	`boolean`	No	Determines whether MagicPrompt should be used to enhance the generation request. - Boolean value: `true` / `false` 示例：`true`。
`input.image_size`	`string`	No	The resolution of the generated image. - `square`: Square - `square_hd`: Square HD - `portrait_4_3`: Portrait 3:4 - `portrait_16_9`: Portrait 9:16 - `landscape_4_3`: Landscape 4:3 - `landscape_16_9`: Landscape 16:9 Allowed values：`square` / `square_hd` / `portrait_4_3` / `portrait_16_9` / `landscape_4_3` / `landscape_16_9`。示例：`square_hd`。
`input.seed`	`integer`	No	Seed for the random number generator.
`input.negative_prompt`	`string`	No	Description of what to exclude from the generated image. If the positive prompt conflicts with the negative prompt, the positive prompt takes precedence. Maximum length: 5000 characters.

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram/v3-text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "A cinematic photograph of a tranquil lakeside at twilight, viewed from a slight elevation. In the center, a cluster of softly glowing reeds and water lilies emit a gentle golden light, their reflections shimmering on the calm surface. The elegant neon-style white text '\''ai.modelfold.online'\'' hovers just above the water, subtly illuminated and harmonizing with the natural glow. Surrounding willows and drifting mist frame the scene, creating a serene yet magical atmosphere, with warm highlights contrasting against the cool blues of the evening sky.",
    "rendering_speed": "BALANCED",
    "style": "AUTO",
    "expand_prompt": true,
    "image_size": "square_hd",
    "seed": 123456,
    "negative_prompt": "blurry, low detail, distorted anatomy, extra limbs, malformed text, watermark"
  }
}'

json

{
  "model": "ideogram/v3-text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "A cinematic photograph of a tranquil lakeside at twilight, viewed from a slight elevation. In the center, a cluster of softly glowing reeds and water lilies emit a gentle golden light, their reflections shimmering on the calm surface. The elegant neon-style white text 'ai.modelfold.online' hovers just above the water, subtly illuminated and harmonizing with the natural glow. Surrounding willows and drifting mist frame the scene, creating a serene yet magical atmosphere, with warm highlights contrasting against the cool blues of the evening sky.",
    "rendering_speed": "BALANCED",
    "style": "AUTO",
    "expand_prompt": true,
    "image_size": "square_hd",
    "seed": 123456,
    "negative_prompt": "blurry, low detail, distorted anatomy, extra limbs, malformed text, watermark"
  }
}

Response

200 — Request successful

参数	类型	必填	说明
`data`	`object`	否	—
`data.taskId`	`string`	否	Task ID, which can be used to query task status through the task detail endpoint. 示例：`task_ideogram_1765180586443`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_ideogram_1765180586443"
  }
}

500 — Server error.

Callback

onImageGenerated

Callback URL: {$request.body#/callBackUrl} (the callBackUrl in the request body).

Sent when the task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	否	200: success. 501: failure; see data.failCode and data.failMsg. Allowed values：`200` / `501`。示例：`200`。
`msg`	`string`	否	Status message 示例：`Playground task completed successfully.`。
`data`	`object`	否	—
`data.completeTime`	`integer`	否	Task completion time as a Unix timestamp in milliseconds 示例：`1786427040000`。
`data.costTime`	`integer`	否	Processing time in seconds. Present on both success and failure callbacks. 示例：`48`。
`data.createTime`	`integer`	否	Task creation time as a Unix timestamp in milliseconds 示例：`1786426989000`。
`data.creditsConsumed`	`number`	否	Credits consumed by the task; 0 for failed tasks. 示例：`7`。
`data.model`	`string`	否	Model used for image generation 示例：`ideogram/v3-text-to-image`。
`data.param`	`string`	否	Parameters submitted when creating the task, formatted as a JSON string 示例：{"model":"ideogram/v3-text-to-image","callBackUrl":"https://your-domain.com/api/callback","input":{"prompt":"A cinematic lakeside photograph at dusk, captured from a slightly elevated angle. At the center of the image, softly glowing reeds and water lilies cast golden reflections on the calm surface of the water. Elegant white neon-style text reading \"ai.modelfold.online\" floats above the water,glowing subtly and blending harmoniously with the natural halo. Weeping willows and light mist surround the scene, creating a peaceful and dreamlike atmosphere. Warm highlights contrast beautifully with the cool blue tones of the evening sky.","rendering_speed":"BALANCED","style":"AUTO","expand_prompt":true,"image_size":"square_hd","seed":123456,"negative_prompt":"Blurry, low resolution, deformed,extra limbs, distorted text, watermark"}}。
`data.resultJson`	`string`	否	Image generation result formatted as a JSON string. `resultUrls` contains the URLs of the generated images. Present only when state is success. 示例：`{"resultUrls":["https://tempfile.aiquickdraw.com/workers/images/image_90b6bf4499a80b74a2b5ee640b7aaf70.webp"]}`。
`data.state`	`string`	否	Task status Allowed values：`success` / `fail`。示例：`success`。
`data.taskId`	`string`	否	Task ID 示例：`4e029a320e97cff234e6e06827c3965e`。
`data.updateTime`	`integer`	否	Use completeTime as the completion time; updateTime may equal createTime. 示例：`1786427040000`。
`data.failCode`	`string`	否	Failure code, a numeric string such as "400" or "500". Present only when state is fail. 示例：`500`。
`data.failMsg`	`string`	否	Failure reason. Present only when state is fail. 示例：`<error detail>`。

Success

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "4e029a320e97cff234e6e06827c3965e",
    "model": "ideogram/v3-text-to-image",
    "state": "success",
    "param": "{\"model\":\"ideogram/v3-text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A cinematic lakeside photograph at dusk, captured from a slightly elevated angle. At the center of the image, softly glowing reeds and water lilies cast golden reflections on the calm surface of the water. Elegant white neon-style text reading \\\"ai.modelfold.online\\\" floats above the water,glowing subtly and blending harmoniously with the natural halo. Weeping willows and light mist surround the scene, creating a peaceful and dreamlike atmosphere. Warm highlights contrast beautifully with the cool blue tones of the evening sky.\",\"rendering_speed\":\"BALANCED\",\"style\":\"AUTO\",\"expand_prompt\":true,\"image_size\":\"square_hd\",\"seed\":123456,\"negative_prompt\":\"Blurry, low resolution, deformed,extra limbs, distorted text, watermark\"}}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/workers/images/image_90b6bf4499a80b74a2b5ee640b7aaf70.webp\"]}",
    "completeTime": 1786427040000,
    "createTime": 1786426989000,
    "costTime": 48,
    "creditsConsumed": 7,
    "updateTime": 1786427040000
  }
}

Failure

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "4e029a320e97cff234e6e06827c3965e",
    "model": "ideogram/v3-text-to-image",
    "state": "fail",
    "param": "{\"model\":\"ideogram/v3-text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A cinematic lakeside photograph at dusk, captured from a slightly elevated angle. At the center of the image, softly glowing reeds and water lilies cast golden reflections on the calm surface of the water. Elegant white neon-style text reading \\\"ai.modelfold.online\\\" floats above the water,glowing subtly and blending harmoniously with the natural halo. Weeping willows and light mist surround the scene, creating a peaceful and dreamlike atmosphere. Warm highlights contrast beautifully with the cool blue tones of the evening sky.\",\"rendering_speed\":\"BALANCED\",\"style\":\"AUTO\",\"expand_prompt\":true,\"image_size\":\"square_hd\",\"seed\":123456,\"negative_prompt\":\"Blurry, low resolution, deformed,extra limbs, distorted text, watermark\"}}",
    "failCode": "500",
    "failMsg": "<error detail>",
    "completeTime": 1786427040000,
    "createTime": 1786426989000,
    "costTime": 48,
    "creditsConsumed": 0,
    "updateTime": 1786427040000
  }
}

Ideogram V3 Text to Image ​

Endpoint ​

Create Task ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

500 — Server error. ​

Callback ​

onImageGenerated ​

Ideogram V3 Text to Image

Endpoint

Create Task

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

500 — Server error.

Callback

onImageGenerated