MoonNexAI API Docs

English

简体中文

English

简体中文

Appearance

Picture asynchronous tasks ​

Asynchronous image APIs handle potentially long generation or editing tasks. Synchronous /v1/images/generations and /v1/images/edits wait until completion; asynchronous endpoints return a task ID first for subsequent polling.

API Path ​

MethodologyPathPurpose
POST/v1/images/generations/asyncCreates a picture asynchronous to generate task.
POST/v1/images/edits/asyncCreates a picture asynchronous edit task.
GET/v1/images/tasks/{task_id}Find pictures asynchronous tasks.
GET/v1/images/tasks/{task_id}/contenttask succeeded and jumped to the result picture.

Create Generate task ​

bash
curl https://moonnexai.com/v1/images/generations/async \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product mockup on a white studio table.",
    "size": "1024x1024",
    "n": 1
  }'

API keys with asynchronous image access can also submit gemini-3-pro-image-preview through this endpoint. Gemini tasks return the same MoonNexAI task ID format and use the same status and result workflow:

bash
curl https://moonnexai.com/v1/images/generations/async \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A premium outdoor lifestyle advertising storyboard proposal board, Chinese typography, warm evening light, professional commercial photography.",
    "size": "16:9",
    "resolution": "4K",
    "n": 1
  }'

Asynchronous access is not enabled for every key or model variant. Requests use verified asynchronous support for the selected model and group; without it, creation fails before a task or charge is created. Check GET /v1/models, the pricing page and your account's capabilities. Size, aspect ratio, resolution and output count also vary by model.

response:

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "queued",
  "progress": 3,
  "model": "gpt-image-2"
}

Create Edit task ​

Picture asynchronous edits the JSON request for the public web image URL or Base64. If you need to upload a local file directly, use synchronous /v1/images/edits.

bash
curl https://moonnexai.com/v1/images/edits/async \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-pro",
    "prompt": "Change the background to a clean studio scene.",
    "image": "https://example.com/product.png",
    "size": "1024x1024"
  }'

Query task ​

bash
curl https://moonnexai.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

Processing:

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "running",
  "progress": 30,
  "model": "gpt-image-2"
}

Success:

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "succeeded",
  "progress": 100,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://media-nex.windfimusic.com/image/example.png"
    }
  ]
}

Failed:

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "failed",
  "progress": 100,
  "model": "gpt-image-2",
  "error": {
    "code": "image_task_failed",
    "message": "Image task failed. Please check prompt, input image, and size."
  }
}

Status statement ​

StatusMeaningTreatment
submittedtask has been submitted.Further queries will be made later.
queuedtask in line.Further queries will be made later.
runningGenerating.Go on polling, recommend 3 to 10 seconds once.
succeededtask succeeded.Read data[].url, or access the center path.
failedtask failed.Read error.message, retry after adjusting the parameters.

Get Picture Contents ​

task has access to:

http
GET /v1/images/tasks/{task_id}/content

The API jumps to the result image URL, which is suitable for browser preview or download. The API integration still recommends that priority be given to query task and save data[].url.

synchronous and asynchronous selection ​

sceneRecommendation API
It is hoped that the results of the photo will be obtained directly at request at a time and that the client will be able to wait./v1/images/generations or /v1/images/edits
task may be slow, client instability and gateway time-limited./v1/images/generations/async or /v1/images/edits/async
The local photo file needs to be uploaded for editing./v1/images/edits
Edit input is already a public web URL or Base64 image content./v1/images/edits/async

If a synchronous connection closes early, the client usually cannot receive the final response. Use an asynchronous endpoint, save the task ID and query it later.

asynchronous image model ​

These models recommend direct use of /v1/images/generations/async to create task and to use /v1/images/tasks/{task_id} query results:

ModelsUsual ModeRecommended sizeResult
seedream-5.0text-to-image, image-to-imagesize, e. g. 2048x2048 or 2048*2048data[].url
seedream-4.5text-to-image, image-to-imagesize, e. g. 2048x2048 or 2048*2048data[].url
wan2.7-image-protext-to-image, image-to-imagesize or model supported aspect ratio parametersdata[].url
gemini-3-pro-image-previewtext-to-imagesize, resolution, taking values based on model capabilitiesdata[].url

For image-to-image requests, provide a public image URL or MoonNexAI-hosted URL accessible to the model. A source image of at least 300x300 is recommended. Avoid URLs requiring login, expiring shortly or blocking automated access.

Check the console, pricing page and GET /v1/models for parameters, sizes, resolutions and output counts. See Gemini Nano synchronous requests for Gemini-compatible calls and Gemini Nano asynchronous requests for the unified task API.

Results Format ​

Picture asynchronous tasks returns URL after success. Even if the image contents are obtained during generation, MoonNexAI will be converted to a visitable URL and write data[].url after writing, and will not return the image Base64 text in the result task.

Relevant Pages ​