# GENGEN API integration guide for LLMs > Build video, image, and multimodal applications with one GENGEN API key and a consistent generation schema. This document is a compact implementation brief for AI coding assistants. The canonical documentation is [docs.gengen.farm](https://docs.gengen.farm). When this summary and an endpoint reference differ, follow the endpoint reference. ## Canonical resources - Documentation: https://docs.gengen.farm - Quickstart: https://docs.gengen.farm/quickstart.md - Authentication: https://docs.gengen.farm/authentication.md - Function calling and Gemini tools: https://docs.gengen.farm/tool-calling.md - OpenAI-compatible LLM guide: https://docs.gengen.farm/openai-compatibility.md - API conventions: https://docs.gengen.farm/api-reference/introduction.md - Model catalog: https://docs.gengen.farm/models/overview.md - Live customer pricing: https://docs.gengen.farm/pricing.md - Errors: https://docs.gengen.farm/help/errors.md - Compatibility notes: https://docs.gengen.farm/help/compatibility.md - Documentation index for LLMs: https://docs.gengen.farm/llms.txt - Full documentation for LLMs: https://docs.gengen.farm/llms-full.txt - Core OpenAPI specification: https://docs.gengen.farm/openapi/gengen-v1.yaml - Kling video OpenAPI specification: https://docs.gengen.farm/openapi/kling-video.yaml - MiniMax video OpenAPI specification: https://docs.gengen.farm/openapi/minimax-video.yaml - API Explorer: https://gengen.farm/api-explorer - Dashboard: https://gengen.farm/dashboard ## API basics Base URL: ```text https://gengen.farm/api/gengen/v1 ``` All requests use HTTPS. Authenticate on the server with a workspace API key: ```http Authorization: Bearer gengen_live_xxxxxxxxxxxxxxxx ``` Never expose a GENGEN API key in browser code, mobile applications, public repositories, logs, or client-side environment variables. Create keys in the [GENGEN Dashboard](https://gengen.farm/dashboard?section=apiKeys&createKey=1). The full secret is displayed only once. ## OpenAI-compatible LLM clients For supported LLM models, existing server-side applications can use the OpenAI Python or JavaScript SDK with the GENGEN Chat Completions compatibility base URL: ```text https://gengen.farm/v1 ``` The SDK appends `/chat/completions`, producing `https://gengen.farm/v1/chat/completions`. Authenticate with a GENGEN workspace API key beginning with `gengen_live_` and use an exact public GENGEN model ID. Python: ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["GENGEN_API_KEY"], base_url="https://gengen.farm/v1", ) completion = client.chat.completions.create( model="seed-2-0-lite-260428", messages=[{"role": "user", "content": "Explain idempotency in two sentences."}], ) print(completion.choices[0].message.content) ``` JavaScript: ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.GENGEN_API_KEY, baseURL: "https://gengen.farm/v1", }); const completion = await client.chat.completions.create({ model: "seed-2-0-lite-260428", messages: [{ role: "user", content: "Explain idempotency in two sentences." }], }); console.log(completion.choices[0].message.content); ``` The `/v1` compatibility base URL currently supports Chat Completions only, including SSE streaming. Do not assume that OpenAI SDK resources such as Responses, Models, Images, Files, or Assistants are available through this base URL. Use the documented canonical GENGEN endpoints for other capabilities. Applications that do not use an OpenAI SDK can call `POST https://gengen.farm/api/gengen/v1/chat/completions` directly. Detailed compatibility guide: https://docs.gengen.farm/openai-compatibility.md ## Rules for new integrations 1. Use the canonical `/api/gengen/v1/*` endpoints for native GENGEN integrations. OpenAI Chat Completions clients may use the documented `https://gengen.farm/v1` compatibility base URL. Legacy `/v1/seedance-2/*` routes exist only for compatibility. 2. Use the exact public model ID from the GENGEN model catalog. 3. Use camelCase request fields. 4. Put media inputs under `assets`. 5. Put provider-neutral generation settings under `controls`. 6. Put advanced provider-specific overrides under `providerOptions`. 7. Read primary response fields in this order: `id`, `model`, `status`, `outputs`. 8. Read videos from `outputs.videos` and images from `outputs.images`. 9. Do not build new integrations around compatibility fields such as `task_id`, `video_url`, `image_url`, `videos`, `images`, `data`, or provider-native containers. 10. Review the selected endpoint and live pricing before sending a billable request. ## Normalized generation request Use this shape for new video and image integrations, with only the fields supported by the selected endpoint and model: ```json { "model": "dreamina-seedance-2-0-260128", "mode": "text_to_video", "prompt": "A cinematic tracking shot through a greenhouse at sunrise.", "assets": {}, "controls": { "duration": 5, "resolution": "720p", "ratio": "16:9" }, "providerOptions": {} } ``` Do not guess supported controls. Read the selected model page and endpoint reference first. ## Standard generation response ```json { "id": "provider:public-task-id", "model": "dreamina-seedance-2-0-260128", "status": "pending", "outputs": { "videos": [], "images": [] } } ``` For asynchronous operations, use `id` to retrieve the task. Treat `succeeded`, `failed`, `cancelled`, and the compatibility status `completed` as terminal states. Do not treat a Seedance provider status of `expired` as terminal: continue polling the same task because it can resume and later succeed. Provider output URLs can expire. Copy successful media to storage controlled by the application when durable access is required. ## Minimal video generation flow Video generation is asynchronous: create a task, then poll the same task with the same API key until it reaches a terminal state. Create a task: ```bash curl --request POST \ --url https://gengen.farm/api/gengen/v1/contents/generations/tasks \ --header 'Authorization: Bearer gengen_live_xxxxxxxxxxxxxxxx' \ --header 'Content-Type: application/json' \ --data '{ "model": "dreamina-seedance-2-0-260128", "mode": "text_to_video", "prompt": "A kitten yawns at the camera in warm morning light.", "controls": { "duration": 5, "resolution": "720p", "ratio": "16:9", "generateAudio": true, "watermark": false } }' ``` Retrieve the result, URL-encoding the task ID when it is inserted into the path: ```bash curl --request GET \ --url https://gengen.farm/api/gengen/v1/contents/generations/tasks/PROVIDER%3ATASK_ID \ --header 'Authorization: Bearer gengen_live_xxxxxxxxxxxxxxxx' ``` Read the completed video URL from `outputs.videos`. Detailed references: - Video generation guide: https://docs.gengen.farm/guides/video-generation.md - Create task: https://docs.gengen.farm/api-reference/byteplus/video-generation/create-task.md - Retrieve task: https://docs.gengen.farm/api-reference/byteplus/video-generation/retrieve-task.md - List tasks: https://docs.gengen.farm/api-reference/byteplus/video-generation/list-tasks.md - Cancel or delete task: https://docs.gengen.farm/api-reference/byteplus/video-generation/cancel-task.md ## Core API surfaces | Capability | Method and path | Behavior | Reference | | --- | --- | --- | --- | | Chat completions | `POST /chat/completions` | Synchronous or SSE streaming | https://docs.gengen.farm/api-reference/byteplus/text-generation/chat-completions.md | | Video tasks | `POST /contents/generations/tasks` | Asynchronous | https://docs.gengen.farm/api-reference/byteplus/video-generation/create-task.md | | Retrieve video task | `GET /contents/generations/tasks/{id}` | Poll task state | https://docs.gengen.farm/api-reference/byteplus/video-generation/retrieve-task.md | | List video tasks | `GET /contents/generations/tasks` | Reads persisted workspace tasks | https://docs.gengen.farm/api-reference/byteplus/video-generation/list-tasks.md | | Cancel or delete video task | `DELETE /contents/generations/tasks/{id}` | Mutates remote and local task state | https://docs.gengen.farm/api-reference/byteplus/video-generation/cancel-task.md | | Image generation | `POST /images/generations` | Synchronous; read `outputs.images` | https://docs.gengen.farm/api-reference/byteplus/image-generation/create-image.md | | Video understanding | `POST /responses` | Synchronous or SSE streaming | https://docs.gengen.farm/api-reference/byteplus/video-understanding/create-response.md | | File upload | `POST /files` | Upload for supported workflows | https://docs.gengen.farm/api-reference/byteplus/files/upload-file.md | Google models use the same authenticated GENGEN API origin with provider-specific references: | Capability | Method and path | Behavior | Reference | | --- | --- | --- | --- | | Gemini chat completions | `POST /chat/completions` | Synchronous or SSE streaming | https://docs.gengen.farm/api-reference/google/chat-completions.md | | Gemini multimodal responses | `POST /responses` | Synchronous or SSE streaming with Gemini 3.8 Flash, 3.7 Flash, or 3.5 Flash-Lite | https://docs.gengen.farm/api-reference/google/responses.md | | Gemini image generation | `POST /images/generations` | Synchronous; URL-only output in `outputs.images`; URLs expire after 24 hours | https://docs.gengen.farm/api-reference/google/image-generation.md | The GENGEN API also exposes provider-specific asynchronous routes for Happy Horse, WonderClip, Flash VSR, Wan, and Qwen. Read the relevant OpenAPI specification before implementing those flows: - Happy Horse video: https://docs.gengen.farm/openapi/happy-horse-video.yaml - Kling video: https://docs.gengen.farm/openapi/kling-video.yaml - MiniMax video: https://docs.gengen.farm/openapi/minimax-video.yaml - WonderClip video: https://docs.gengen.farm/openapi/wonderclip-video.yaml - WonderClip image: https://docs.gengen.farm/openapi/wonderclip-image.yaml - Flash VSR video: https://docs.gengen.farm/openapi/flash-vsr-video.yaml - Wan video: https://docs.gengen.farm/openapi/wan-video.yaml - Wan face swap: https://docs.gengen.farm/openapi/wan-face-swap.yaml - Wan z-image: https://docs.gengen.farm/openapi/wan-z-image.yaml - Qwen Image 3: https://docs.gengen.farm/openapi/qwen-image-3.yaml - Qwen image edit: https://docs.gengen.farm/openapi/qwen-image-edit.yaml - BytePlus assets: https://docs.gengen.farm/openapi/byteplus-assets.yaml ## Current public model IDs Always verify availability and live customer pricing in the Dashboard before production use. ### Google Google image models return public HTTPS URLs only. Generated image URLs are retained for 24 hours; copy them to storage you control before `outputs.expiresAt`. - `gemini-3.8-flash` — [Gemini 3.8 Flash](https://docs.gengen.farm/models/gemini-3.8-flash.md); supports LLM chat, SSE streaming, and multimodal video understanding with synchronous or SSE Responses; reasoning levels: low, medium (default), high - `gemini-3.7-flash` — [Gemini 3.7 Flash](https://docs.gengen.farm/models/gemini-3.7-flash.md); supports SSE streaming through Chat Completions and synchronous or SSE multimodal Responses - `gemini-3.5-flash-lite` — [Gemini 3.5 Flash-Lite](https://docs.gengen.farm/models/gemini-3.5-flash-lite.md); supports fast structured text generation, SSE streaming, and synchronous or SSE multimodal Responses - `gemini-3-pro-image` — [Nano Banana Pro (Gemini 3 Pro Image)](https://docs.gengen.farm/models/gemini-3-pro-image.md) - `gemini-3.1-flash-image` — [Nano Banana 2 (Gemini 3.1 Flash Image)](https://docs.gengen.farm/models/gemini-3.1-flash-image.md) - `gemini-3.1-flash-lite-image` — [Nano Banana 2 Lite (Gemini 3.1 Flash-Lite Image)](https://docs.gengen.farm/models/gemini-3.1-flash-lite-image.md) ### Video - `kling-3.0-turbo` — [Kling 3.0 Turbo](https://docs.gengen.farm/models/kling-3.0-turbo.md) - `kling-3.0` — [Kling 3.0](https://docs.gengen.farm/models/kling-3.0.md) - `kling-3.0-omni` — [Kling 3.0 Omni](https://docs.gengen.farm/models/kling-3.0-omni.md) - `minimax-h3` — [MiniMax H3](https://docs.gengen.farm/models/minimax-h3.md) - `minimax-h3-max` — [MiniMax H3 Max](https://docs.gengen.farm/models/minimax-h3-max.md) - `dreamina-seedance-2-5-260628` — [Seedance 2.5](https://docs.gengen.farm/models/dreamina-seedance-2-5-260628.md) - `dreamina-seedance-2-0-260128` — [Seedance 2.0](https://docs.gengen.farm/models/dreamina-seedance-2-0-260128.md) - `dreamina-seedance-2-0-fast-260128` — [Seedance 2.0 Fast](https://docs.gengen.farm/models/dreamina-seedance-2-0-fast-260128.md) - `dreamina-seedance-2-0-mini-260615` — [Seedance 2.0 Mini](https://docs.gengen.farm/models/dreamina-seedance-2-0-mini-260615.md) - `seedance-1-5-pro-251215` — [Seedance 1.5 Pro](https://docs.gengen.farm/models/seedance-1-5-pro-251215.md) - `wan2.7-i2v-spicy` — [Wan 2.7 Image-to-Video](https://docs.gengen.farm/models/wan2.7-i2v-spicy.md) - `wan-animate` — [Wan Animate](https://docs.gengen.farm/models/wan-animate.md) - `flashvsr` — [Flash VSR](https://docs.gengen.farm/models/flashvsr.md) - `happyhorse-1.1` — [Happy Horse 1.1](https://docs.gengen.farm/models/happyhorse-1.1.md) - `wonder-pro` — [WonderClip Pro](https://docs.gengen.farm/models/wonder-pro.md) - `wonder-standard` — [WonderClip Standard](https://docs.gengen.farm/models/wonder-standard.md) - `wonder-happyhorse-1.1` — [WonderClip Happy Horse 1.1](https://docs.gengen.farm/models/wonder-happyhorse-1.1.md) - `wonder-happyhorse-1.0` — [WonderClip Happy Horse 1.0](https://docs.gengen.farm/models/wonder-happyhorse-1.0.md) ### Image - `seedream-5-0-260128` — [Seedream 5.0 Lite](https://docs.gengen.farm/models/seedream-5-0-260128.md) - `dola-seedream-5-0-pro-260628` — [Seedream 5.0 Pro](https://docs.gengen.farm/models/dola-seedream-5-0-pro-260628.md) - `z-image-spicy` — [z-image Text-to-Image](https://docs.gengen.farm/models/z-image-spicy.md) - `wan-face-swap` — [Wan Face Swap](https://docs.gengen.farm/models/wan-face-swap.md) - `qwen-image-3-0` — [Qwen Image 3.0](https://docs.gengen.farm/models/qwen-image-3-0.md) - `qwen-image-edit-spicy` — [Qwen Image Edit](https://docs.gengen.farm/models/qwen-image-edit-spicy.md) - `wonder-banana-pro` — [WonderClip Banana Pro](https://docs.gengen.farm/models/wonder-banana-pro.md) - `wonder-image-2` — [WonderClip Image 2](https://docs.gengen.farm/models/wonder-image-2.md) ### LLM and multimodal reasoning - `dola-seed-2-1-turbo-260628` — [Seed 2.1 Turbo](https://docs.gengen.farm/models/dola-seed-2-1-turbo-260628.md) - `seed-2-0-mini-260428` — [Seed 2.0 Mini](https://docs.gengen.farm/models/seed-2-0-mini-260428.md) - `seed-2-0-lite-260428` — [Seed 2.0 Lite](https://docs.gengen.farm/models/seed-2-0-lite-260428.md) - `seed-2-0-pro-260328` — [Seed 2.0 Pro](https://docs.gengen.farm/models/seed-2-0-pro-260328.md) - `seed-2-0-code-preview-260328` — [Seed 2.0 Code Preview](https://docs.gengen.farm/models/seed-2-0-code-preview-260328.md) - `deepseek-v4-flash-260425` — [DeepSeek V4 Flash](https://docs.gengen.farm/models/deepseek-v4-flash-260425.md) - `deepseek-v4-pro-260425` — [DeepSeek V4 Pro](https://docs.gengen.farm/models/deepseek-v4-pro-260425.md) - `glm-5-2-260617` — [GLM 5.2](https://docs.gengen.farm/models/glm-5-2-260617.md) ## Errors GENGEN errors use a stable envelope: ```json { "error_code": "gengen.model_required", "error_params": { "field": "model" }, "error": "A model is required" } ``` Branch on `error_code`, not on the human-readable message. Fix `4xx` request errors before retrying. Retry transient `5xx` and rate-limit responses with exponential backoff and jitter. Never log API keys. Common HTTP statuses: - `400`: invalid request, model, mode, or provider input - `401`: missing or invalid API key - `402`: insufficient available balance - `403`: revoked, expired, or unauthorized API key - `404`: task unavailable in the current API-key scope - `501`: unsupported operation for the selected provider - `5xx`: GENGEN or upstream provider failure ## Billing and task safety - Generation requests may be billable. Check the [live pricing page](https://docs.gengen.farm/pricing.md) and endpoint reference before sending a request. - Creating an asynchronous task can reserve wallet balance while the task runs. - Retrieving a successful terminal result can finalize the corresponding charge. - Failed or cancelled tasks are released or remain non-billable according to the endpoint lifecycle. - Use stable task or request IDs for application-side idempotency and audit logs. - Do not repeatedly create a task when the intended operation is to poll an existing task. - Deleting or cancelling a task changes remote and local task state. ## Implementation checklist for coding agents Before writing code: 1. Identify the requested capability and model. 2. Read the model page, endpoint reference, and relevant OpenAPI specification. 3. Confirm whether the endpoint is synchronous or asynchronous and whether it is billable. 4. Confirm the exact request schema, supported controls, and media requirements. 5. Keep the API key in server-side configuration. When implementing: 1. Start with the smallest end-to-end request. 2. Use the normalized request and standard response fields. 3. For async tasks, persist the returned `id`, URL-encode it in path segments, and poll at a reasonable interval. 4. Handle all terminal states and the stable error envelope. 5. Preserve provider output files if durable access is required. 6. Add tests for success, invalid input, authentication failure, insufficient balance, provider failure, and async terminal states as relevant. 7. Do not expose internal billing formulas or infer unsupported provider behavior. ### LLM tools All listed Seed, DeepSeek, GLM, and Gemini LLMs support Function Call through Chat Completions, including SSE. Preserve assistant tool calls, reasoning fields, and provider metadata across turns. Gemini 3.8 Flash, 3.7 Flash, and 3.5 Flash-Lite also accept Code execution and Computer use through `providerOptions.google.tools`, on Chat Completions and synchronous or SSE Responses. See https://docs.gengen.farm/tool-calling.md for request examples and execution responsibilities. All 11 listed LLMs support Chat Completions SSE. Public Responses SSE is available for the three Gemini models and Seed 2.0 Lite, Seed 2.0 Pro, and Seed 2.1 Turbo. Responses emits typed terminal events with usage after settlement; background execution is not supported. ## OpenAI image models Reference images use `assets.referenceImages` with up to 16 HTTPS URLs. Base64 data URLs and raw Base64 inputs are not supported. Call `POST https://gengen.farm/api/gengen/v1/images/generations` with a GENGEN bearer key. Both generation and reference-image editing use the normalized `assets` / `controls` schema; native `n` maps to `controls.outputCount`. This canonical endpoint uses GENGEN's contract rather than native OpenAI Images SDK payloads. Responses contain HTTPS URLs in `outputs.images` and a 24-hour `outputs.expiresAt`; streaming is not supported. GPT Image 2.5 adds `xhigh` and `max` quality; GENGEN defaults to `medium` and `1024x1024` for all three models. - `gpt-image-2.5-flare`: https://docs.gengen.farm/models/gpt-image-2.5-flare - `gpt-image-2.5-sunburst`: https://docs.gengen.farm/models/gpt-image-2.5-sunburst - `gpt-image-2`: https://docs.gengen.farm/models/gpt-image-2 - Image generation and editing: https://docs.gengen.farm/api-reference/openai/image-generation ## Higgsfield video generation - Independent provider with asynchronous generation, wallet reservations and completion billing. - `higgsfield-seedance-2.0` — [Seedance 2.0 (Higgsfield)](https://docs.gengen.farm/models/higgsfield-seedance-2.0.md) - `higgsfield-seedance-2.5` — [Seedance 2.5 (Higgsfield)](https://docs.gengen.farm/models/higgsfield-seedance-2.5.md) - [Higgsfield API reference](https://docs.gengen.farm/api-reference/higgsfield/video-generation/overview.md) - [Higgsfield OpenAPI](https://docs.gengen.farm/openapi/higgsfield-video.yaml)