kling-omni-image
Generate high-quality AI images using Kling's Omni-Image model via an async submit→poll workflow. Supports text prompts, reference images (URL or Base64), element library composition, resolutions up t
SKILL.mdresources/migrated/v1-skills/kling-omni-image/SKILL.md
GitHubKling Omni-Image — Image Generation
Overview
Based on Kling AI's Omni-Image model, supports generating high-quality images via text prompts, reference images (URL or Base64), and element library resources. Supports 1k/2k resolution, multiple aspect ratios, and two output modes: single image (single) and image series (series).
Workflow (async):
- Call the submit endpoint (POST) to create a generation task and obtain a
task_id - Poll the query endpoint (GET) until
task_statusbecomessucceedorfailed - Retrieve image URLs from
task_result.images(single mode) ortask_result.series_images(series mode) - Transfer image URLs to Supabase Storage (CDN links expire after 30 days)
Read
references/submit-api.mdfor the full specification and code for the submit endpoint. Readreferences/query-api.mdfor the full specification and code for the query endpoint.
Complete Async Workflow
const apiKey = process.env["INTEGRATIONS_API_KEY"]!;
async function generateOmniImage(params: SubmitParams): Promise<ImageResult[]> {
// Step 1: Submit task
const submitResp = await fetch("https://app-dohnbj5by5mp-api-2Y00Vzbe0MBY.gateway.appmedo.com/v1/images/omni-image", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Gateway-Authorization": `Bearer ${apiKey}`,
},
body: JSON.stringify(params),
});
if (!submitResp.ok) throw new Error(`Submit HTTP error: ${submitResp.status}`);
const submitJson = await submitResp.json();
if (submitJson.code !== 0) throw new Error(`Submit API error ${submitJson.code}: ${submitJson.message}`);
const taskId: string = submitJson.data.task_id;
// Step 2: Poll until done
const POLL_INTERVAL_MS = 7000;
const TIMEOUT_MS = 10 * 60 * 1000;
const deadline = Date.now() + TIMEOUT_MS;
while (Date.now() < deadline) {
await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
const queryResp = await fetch(
`https://app-dohnbj5by5mp-api-n9QVxo8blgrL.gateway.appmedo.com/v1/images/omni-image/${taskId}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
"X-Gateway-Authorization": `Bearer ${apiKey}`,
},
}
);
if (!queryResp.ok) throw new Error(`Query HTTP error: ${queryResp.status}`);
const queryJson = await queryResp.json();
if (queryJson.code !== 0) throw new Error(`Query API error ${queryJson.code}: ${queryJson.message}`);
const status: string = queryJson.data.task_status;
if (status === "succeed") {
const result = queryJson.data.task_result;
// Return images array (single mode) or series_images (series mode)
return result.images?.length > 0 ? result.images : result.series_images ?? [];
}
if (status === "failed") {
throw new Error(`Task failed: ${queryJson.data.task_status_msg}`);
}
// submitted / processing → keep polling
}
throw new Error(`Task ${taskId} timed out after 10 minutes`);
}
Important constraints (must be followed):
- When
result_type = single: theseries_amountfield must NOT appear in the request body - When
result_type = series:series_amountmust be provided, range [2, 9] - Base64 images must be raw encoded content, without prefixes like
data:image/jpeg;base64,
Generation-time File Download (Required)
The URLs returned by the generation API are temporary CDN links that expire after 30 days. During generation time (Agent direct call scenario), after obtaining a URL, you must immediately use the Bash tool to download the file locally so the user can view the result.
curl -L -o <local-path>.jpg "<generated image URL>"
Complete generation-time workflow (including download step):
- Call
generateOmniImage()to execute the submit → poll loop and obtain the list of image URLs - For each image, use the Bash tool to run
curl -L -o <local-path> "<url>"to download the file locally - Notify the user of the file paths where images have been saved
Note: Upstream CDN links expire after 30 days. Download immediately after obtaining the URL — do not delay.
Generation-time Usage (Agent Direct Call)
See the "Generation-time Usage" section in references/submit-api.md for the complete TypeScript call example.
See the "Generation-time Usage" section in references/query-api.md for the query endpoint call example.
Post-generation Usage (In-app via Edge Function)
See the "Post-generation Usage" section in references/submit-api.md for the Edge Function code for the submit endpoint (including Supabase Storage transfer logic).
See the "Post-generation Usage" section in references/query-api.md for the Edge Function code for the query endpoint.
Notes
- Key security:
INTEGRATIONS_API_KEYmay only be read server-side in an Edge Function — never expose it to the frontend. - Error handling: Always handle 429 (quota exceeded) and 402 (insufficient balance).
- Note: The submit (create task) endpoint is billed. The query endpoint (polling) is not billed. Avoid unnecessary duplicate submissions.
- Image storage: Generated image URLs are valid for 30 days — transfer them to Supabase Storage or another persistent store promptly.
- series_amount constraint: When
result_type=single, passingseries_amountis strictly forbidden and will cause the request to fail. - Base64 images: Must not include the
data:image/...;base64,prefix — pass only the raw encoded string. - Image size limits: Each reference image must not exceed 10MB, minimum size 300px, aspect ratio between 1:2.5 and 2.5:1.