Image Generation Guide
Learn how to create images with UnderSky, submit prompts and reference images, poll asynchronous tasks, and receive callbacks.
Image generation uses an asynchronous two-step workflow: create a task, then poll for the result.
Supported Models
gpt-4o-image— OpenAI GPT-4o image generation, 0.5 credits per image.gpt-image-2— OpenAI GPT Image 2, 0.01 credits per image. Supports aspect-ratiosizevalues like"9:16"in addition to fixed dimensions.gemini-3.1-flash-image-preview— Google Gemini 3.1 Flash Image Preview, approximately 0.081714 credits per image.
Step 1 — Create a Task
curl -X POST https://api.undersky.ai/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "A watercolor painting of a mountain lake at sunrise"
}'{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}Step 2 — Poll for Status
Use the returned id to check progress:
curl https://api.undersky.ai/v1/images/generations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer sk-your-api-key"{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"images": [
{
"id": "image-abc123",
"url": "https://cdn.example.com/images/generated/abc123?token=example"
}
]
}
}Status Values
| Status | Meaning |
|---|---|
reserved | Credits reserved; waiting for a current worker to claim the task. |
pending | Task queued, not yet started. |
processing | Model is generating the image. |
uploading | Image is being uploaded to storage. |
partial | Some images ready (for multi-image requests). |
completed | All images ready. |
failed | Generation failed. |
Webhook Callback
Instead of polling, you can provide a callbackUrl to receive a POST notification when the task finishes:
{
"model": "gpt-4o-image",
"prompt": "A neon-lit cyberpunk cityscape",
"callbackUrl": "https://your-server.com/webhook/image"
}The final charge is the model price multiplied by the number of images produced. Failed tasks release the reserved credits; partial tasks charge only for successful images.
Image URLs are signed when you poll the task and expire after 1 hour. Use the latest value from data.images[].url; poll the task again when you need a fresh URL.
For the full parameter list and response schema, see the API Reference.
Transcribe audio
Send an audio file to UnderSky's OpenAI-compatible transcription endpoint, choose a model and response format, and handle minimum billing and recovery errors.
Video Extract Guide
Learn how to extract video metadata from social media share links, authenticate requests, handle responses, and track fixed-price usage.