curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "kling-o3-image",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A cinematic futuristic alley with rain and neon reflections",
"resolution": "4K",
"size": "16:9",
"output_format": "png",
"n": 2
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 401,
"error": {
"message": "Unauthorized - Invalid API key",
"type": "authentication_error"
}
}Kling
Kling-o3
The Kling O3 API generates images from a prompt or edits 1 to 10 reference images. Resolution is 1K, 2K, or 4K, and optional elements can lock a character or object.
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "kling-o3-image",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A cinematic futuristic alley with rain and neon reflections",
"resolution": "4K",
"size": "16:9",
"output_format": "png",
"n": 2
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 401,
"error": {
"message": "Unauthorized - Invalid API key",
"type": "authentication_error"
}
}- After submission, a
task_idwill be returned. If you provided acallback_url, when the task status becomesfinishedorfailed, a POST request will be sent to thecallback_url. - Regardless of whether
callback_urlis provided, you can retrieve the result through the unified Query Task Status endpoint.
Models
- kling-o3-image - Prompt-only image generation
- kling-o3-image-edit - Image editing with reference images
Required parameters
prompt- Required generation or editing prompt
Optional parameters
image_urls- Optional reference image URLs,1-10images, used for image editing modeelements- Optional array of element descriptors for character/object control. Reference them in prompt as@Element1,@Element2, etc. Recommended structure:frontal_image_urlfor the main face/object image, and optionalreference_image_urlsfor additional reference viewsresolution-1K,2K,4Ksize- Forkling-o3-image:16:9,9:16,1:1,4:3,3:4,3:2,2:3,21:9; forkling-o3-image-edit:auto,16:9,9:16,1:1,4:3,3:4,3:2,2:3,21:9output_format-jpeg,png,webpn- Number of output images,1-9
Examples
Use the unified submit endpoint:POST /api/generate/submit
Prompt-only example:
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-o3-image",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A cinematic futuristic alley with rain and neon reflections",
"resolution": "4K",
"size": "16:9",
"output_format": "png",
"n": 2
}
}'
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-o3-image-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Turn the reference scene into a luxury night interior with dramatic window light",
"image_urls": ["https://example.com/reference1.png"],
"resolution": "4K",
"size": "auto",
"output_format": "png",
"n": 1
}
}'
Notes
Elements Notes
elementsis intended for upstream face/object control- Recommended element fields:
frontal_image_url: public image URL for the main character/object viewreference_image_urls: optional array of additional public image URLs
elementsis optional and should only be used when you need stronger subject consistency
Authorizations
All API endpoints require Bearer Token authentication.
Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.
Add it to the request header:
Authorization: Bearer YOUR_API_KEY
Body
application/json
Response
Task submitted successfully
Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.
200: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
Available options:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 Example:
200