> For the complete documentation index, see [llms.txt](https://docs.fastrouter.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastrouter.ai/api-reference/image/image-generation.md).

# Image Generation

## Generate Image

> Generates images from text prompts.\
> \
> FastRouter supports both synchronous and asynchronous image generation.\
> \
> By default, if \`response\_type\` is omitted, FastRouter prefers a synchronous provider whenever one is available. If no synchronous provider exists for the selected model, FastRouter automatically falls back to an asynchronous provider.\
> \
> Set \`response\_type\` to explicitly control execution:\
> \
> \- \`sync\` — Return the generated image directly.\
> \- \`async\` — Return a \`taskId\`. Retrieve the completed image using GET /api/v1/images/{task\_id} or POST /api/v1/getAsyncResponse.\
> \
> Supported models include OpenAI, Google, Leonardo AI, Black Forest Labs (Flux), ByteDance (Seedream), xAI (Grok), and others.\
> \
> \> \*\*Tip:\*\* Call \*\*GET /api/v1/models\*\* to retrieve the latest models and their supported parameters.

```json
{"openapi":"3.1.0","info":{"title":"FastRouter API Reference","version":"1.0.0"},"tags":[{"name":"Images","description":"Generate and edit images using AI models like OpenAI GPT Image, Google Imagen/Gemini, Flux, Seedream, Grok, and Leonardo."}],"servers":[{"url":"https://api.fastrouter.ai","description":"Production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"FastRouter API Key. Get yours at https://fastrouter.ai\n\nFormat: `Authorization: Bearer YOUR_API_KEY`"}},"schemas":{"ImageGenerationResponse":{"type":"object","description":"Synchronous image generation response.","properties":{"created":{"type":"integer","description":"Unix timestamp of when the image was created"},"data":{"type":"array","description":"Array of generated images","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL of the generated image (if response_format=url)"},"b64_json":{"type":"string","description":"Base64-encoded image data (if response_format=b64_json)"},"revised_prompt":{"type":"string","description":"The revised prompt used by the model, where supported."}}}}}}}},"paths":{"/api/v1/images/generations":{"post":{"operationId":"createImage","tags":["Images"],"summary":"Generate Image","description":"Generates images from text prompts.\n\nFastRouter supports both synchronous and asynchronous image generation.\n\nBy default, if `response_type` is omitted, FastRouter prefers a synchronous provider whenever one is available. If no synchronous provider exists for the selected model, FastRouter automatically falls back to an asynchronous provider.\n\nSet `response_type` to explicitly control execution:\n\n- `sync` — Return the generated image directly.\n- `async` — Return a `taskId`. Retrieve the completed image using GET /api/v1/images/{task_id} or POST /api/v1/getAsyncResponse.\n\nSupported models include OpenAI, Google, Leonardo AI, Black Forest Labs (Flux), ByteDance (Seedream), xAI (Grok), and others.\n\n> **Tip:** Call **GET /api/v1/models** to retrieve the latest models and their supported parameters.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt","model"],"properties":{"prompt":{"type":"string","description":"Text description of the desired image"},"model":{"type":"string","enum":["openai/gpt-image-1","openai/gpt-image-1-mini","openai/gpt-image-1.5","openai/gpt-image-2","google/imagen-4.0","google/imagen-4.0-fast","google/imagen-4.0-ultra","google/gemini-2.5-flash-image","google/gemini-3-pro-image-preview","google/gemini-3.1-flash-image-preview","google/gemini-3.1-flash-lite-image","black-forest-labs/flux-dev","black-forest-labs/flux-kontext-pro","black-forest-labs/flux-pro-2.0","bytedance/seedream-4.0","bytedance/seedream-4.5","x-ai/grok-imagine-image","x-ai/grok-imagine-image-quality","leonardo-ai/phoenix","leonardo-ai/lucid-origin","leonardo-ai/lucid-realism"],"description":"Image generation model to use.\n\nModels may support synchronous or asynchronous execution depending on the available providers.\n\nIf `response_type` is omitted, FastRouter automatically selects the best available provider, preferring synchronous execution and falling back to asynchronous when necessary.\n\nCall GET /api/v1/models for the latest supported models."},"response_type":{"type":"string","enum":["sync","async"],"nullable":true,"description":"Controls how the image generation request is processed.\n\n- `sync` — Force a synchronous provider. The generated image is returned directly in the response.\n- `async` — Force an asynchronous provider. The response returns a `taskId`; retrieve the completed image using GET /api/v1/images/{task_id} or POST /api/v1/getAsyncResponse.\n- Omit this field to let FastRouter automatically select the best provider, preferring synchronous execution and falling back to asynchronous when necessary."},"n":{"type":"integer","minimum":1,"maximum":10,"default":1,"nullable":true,"description":"Number of images to generate. Supported range varies by model."},"size":{"type":"string","nullable":true,"default":"auto","description":"Image dimensions. Supported values vary by model, e.g. gpt-image-1/mini: auto, 1024×1024, 1536×1024, 1024×1536. Check GET /api/v1/models for per-model supported sizes."},"quality":{"type":"string","nullable":true,"default":"auto","enum":["auto","high","medium","low","hd","standard"],"description":"Image quality level (model-specific), e.g. gpt-image-1/mini: auto, high, medium, low. Check GET /api/v1/models for per-model supported values."},"output_format":{"type":"string","nullable":true,"default":"png","enum":["png","jpeg","webp"],"description":"Output image format. Only supported for gpt-image-1 and gpt-image-1-mini"},"background":{"type":"string","nullable":true,"default":"auto","enum":["transparent","opaque","auto"],"description":"Background style. Only for gpt-image-1 and gpt-image-1-mini. Note: transparent requires png or webp format"},"style":{"type":"string","enum":["vivid","natural"],"default":"vivid","description":"Image style, where supported by the model."},"response_format":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Format of the response data"}}}}}},"responses":{"200":{"description":"Successful response.\n\nIf the request is processed synchronously, the generated image (URL or base64) is returned directly.\n\nIf the request is processed asynchronously, the response contains a `taskId`. Poll GET /api/v1/images/{task_id} or POST /api/v1/getAsyncResponse until the image is ready.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ImageGenerationResponse"},{"type":"object","description":"Asynchronous image generation response.","properties":{"taskId":{"type":"string","description":"Identifier for an asynchronous image generation request."}},"required":["taskId"]}]}}}},"400":{"description":"Bad Request - Invalid parameters"},"401":{"description":"Unauthorized - Invalid API key"},"429":{"description":"Rate Limit Exceeded"},"500":{"description":"Internal Server Error"}}}}}}
```

#### **Note:** Leonardo models (`leonardo/...`) respond asynchronously and return a `taskId`. Retrieve the completed image by polling the async response endpoint using either the **GET** or **POST** method.

## Get Image Status

> Retrieves the status and result of an asynchronous image generation by its \`task\_id\` (e.g. Leonardo models, which return a \`task\_id\` from POST /api/v1/images/generations).\
> \
> Poll this endpoint until the image is ready. When complete, \`data\[]\` contains the generated image URL(s) and \`fastrouter\_assets.status\` is \`ready\`.

```json
{"openapi":"3.1.0","info":{"title":"FastRouter API Reference","version":"1.0.0"},"tags":[{"name":"Images","description":"Generate and edit images using AI models like OpenAI GPT Image, Google Imagen/Gemini, Flux, Seedream, Grok, and Leonardo."}],"servers":[{"url":"https://api.fastrouter.ai","description":"Production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"FastRouter API Key. Get yours at https://fastrouter.ai\n\nFormat: `Authorization: Bearer YOUR_API_KEY`"}},"responses":{"UnauthorizedError":{"description":"Invalid Credentials - Your API key is invalid, missing, or disabled. Check your credentials.\n\nNote: the 401 error body uses `code`, `message`, `param`, and `type` (there is no `status` field), and `type` is `invalid_request_error`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":"string","nullable":true},"code":{"type":"string"}}}}}}}},"RateLimitError":{"description":"Rate Limited - You have exceeded your request limits (TPM/RPM). Slow down or increase your limits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"status":{"type":"integer"}}}}}}}}}},"paths":{"/api/v1/images/{task_id}":{"get":{"operationId":"getImageStatus","tags":["Images"],"summary":"Get Image Status","description":"Retrieves the status and result of an asynchronous image generation by its `task_id` (e.g. Leonardo models, which return a `task_id` from POST /api/v1/images/generations).\n\nPoll this endpoint until the image is ready. When complete, `data[]` contains the generated image URL(s) and `fastrouter_assets.status` is `ready`.","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"},"description":"The task ID returned from POST /api/v1/images/generations (e.g. a Leonardo `leo_` prefixed ID)."}],"responses":{"200":{"description":"Image generation status / result","content":{"application/json":{"schema":{"type":"object","properties":{"chat_id":{"type":"string","description":"FastRouter transaction ID for this generation."},"created":{"type":"integer","description":"Unix timestamp when the image was created."},"data":{"type":"array","description":"Array of generated images.","items":{"type":"object","properties":{"id":{"type":"string","description":"Provider-side image/generation ID."},"url":{"type":"string","format":"uri","description":"URL of the generated image."}}}},"fastrouter_assets":{"type":"object","description":"FastRouter-hosted copies of the generated assets.","properties":{"status":{"type":"string","description":"Asset availability status."},"urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"FastRouter-hosted asset URLs."},"expires_at":{"type":"integer","description":"Unix timestamp when the hosted assets expire."},"cached_at":{"type":"integer","description":"Unix timestamp when the assets were cached."}}},"size":{"type":"string","description":"Image dimensions."},"usage":{"type":"object","description":"Credit and token usage for the generation.","properties":{"user_key_credits_used":{"type":"number"},"api_key_credits_used":{"type":"number"},"credits_used":{"type":"number"},"provider":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Task not found or expired"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"description":"Internal Server Error"}}}}}}
```

## Get Async Response

> Polls for asynchronous video generation results. Poll with the \`taskId\` returned from POST /api/v1/videos until status is \`succeed\` or \`completed\`, then download from the provided URL.\
> \
> \*\*taskId and model rules:\*\*\
> \- If \`taskId\` includes a provider prefix (e.g. \`pol\_\` for Pollo), then \*\*model is optional\*\*.\
> \- If \`taskId\` has no provider prefix, then \*\*model is required\*\* and must match the model used in the original /videos request.\
> \
> \*\*Response shape varies by provider:\*\*\
> \- \*\*Pollo\*\* — per-generation \`id\`, \`createdDate\`, \`status\`, \`url\`, etc.\
> \- \*\*Kling\*\* — \`data.status: completed\`; generations have \`duration\` and \`url\`.\
> \- \*\*Veo (Google)\*\* — \`data.status: completed\`; generations have \`bytesBase64Encoded\`. Use \`fastrouter\_assets.urls\` for download.\
> \- \*\*Sora\*\* — OpenAI-style response with \`progress\`, \`status\`, etc.

```json
{"openapi":"3.1.0","info":{"title":"FastRouter API Reference","version":"1.0.0"},"tags":[{"name":"Video","description":"Generate videos from text prompts or images using video generation models."}],"servers":[{"url":"https://api.fastrouter.ai","description":"Production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"FastRouter API Key. Get yours at https://fastrouter.ai\n\nFormat: `Authorization: Bearer YOUR_API_KEY`"}},"responses":{"UnauthorizedError":{"description":"Invalid Credentials - Your API key is invalid, missing, or disabled. Check your credentials.\n\nNote: the 401 error body uses `code`, `message`, `param`, and `type` (there is no `status` field), and `type` is `invalid_request_error`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":"string","nullable":true},"code":{"type":"string"}}}}}}}},"RateLimitError":{"description":"Rate Limited - You have exceeded your request limits (TPM/RPM). Slow down or increase your limits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"status":{"type":"integer"}}}}}}}}}},"paths":{"/api/v1/getAsyncResponse":{"post":{"operationId":"getAsyncResponse","tags":["Video"],"summary":"Get Async Response","description":"Polls for asynchronous video generation results. Poll with the `taskId` returned from POST /api/v1/videos until status is `succeed` or `completed`, then download from the provided URL.\n\n**taskId and model rules:**\n- If `taskId` includes a provider prefix (e.g. `pol_` for Pollo), then **model is optional**.\n- If `taskId` has no provider prefix, then **model is required** and must match the model used in the original /videos request.\n\n**Response shape varies by provider:**\n- **Pollo** — per-generation `id`, `createdDate`, `status`, `url`, etc.\n- **Kling** — `data.status: completed`; generations have `duration` and `url`.\n- **Veo (Google)** — `data.status: completed`; generations have `bytesBase64Encoded`. Use `fastrouter_assets.urls` for download.\n- **Sora** — OpenAI-style response with `progress`, `status`, etc.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taskId"],"properties":{"taskId":{"type":"string","description":"The taskId returned from POST /api/v1/videos. When it includes a provider prefix (e.g. pol_ for Pollo), model can be omitted."},"model":{"type":"string","description":"The video model used in the original /videos request. Required when taskId has no provider prefix; optional when taskId has a provider prefix (e.g. pol_)."}}}}}},"responses":{"200":{"description":"Video generation status or completed video","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Pollo / Kling / Veo response (most video models)","properties":{"chat_id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"taskId":{"type":"string"},"status":{"type":"string","enum":["waiting","processing","succeed","completed","failed"],"description":"Overall status (Kling/Veo). Pollo uses per-generation status instead."},"generations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pollo"},"createdDate":{"type":"string","description":"Pollo"},"updatedDate":{"type":"string","description":"Pollo"},"status":{"type":"string","enum":["waiting","processing","succeed","failed"],"description":"Pollo"},"failMsg":{"type":"string","description":"Pollo"},"url":{"type":"string","format":"uri","description":"Pollo, Kling"},"mediaType":{"type":"string","description":"Pollo"},"duration":{"type":"integer","description":"Kling — duration in seconds"},"bytesBase64Encoded":{"type":"string","description":"Veo — base64 video bytes"}}}}}},"fastrouter_assets":{"type":"object","properties":{"status":{"type":"string"},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"expires_at":{"type":"integer"},"cached_at":{"type":"integer"}}},"usage":{"type":"object"}}},{"type":"object","description":"Sora model response","properties":{"id":{"type":"string"},"chat_id":{"type":"string"},"object":{"type":"string"},"created_at":{"type":"integer"},"status":{"type":"string","enum":["queued","in_progress","completed","failed"]},"progress":{"type":"integer","description":"Completion percentage (0-100)"},"completed_at":{"type":"integer"},"model":{"type":"string"},"seconds":{"type":"string"},"size":{"type":"string"},"usage":{"type":"object"}}}]}}}},"400":{"description":"Bad Request - Invalid taskId or model"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Not Found - Invalid taskId or expired result"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"description":"Internal Server Error"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fastrouter.ai/api-reference/image/image-generation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.