GenCraft.ccGenCraft.cc

API Reference

POST /api/v1/generate · GET /api/v1/tasks

Public endpoints for batch and agent integrations. Authenticate with the API key already issued to your account — no separate token required.

Authentication

Include your API key in the Authorization header. The key is the same one assigned to your account in user_keys (provided by GenCraft after your plan is activated). A bad key returns 401.

HEADER
Authorization: Bearer <your_api_key>
401 RESPONSE
{ "error": { "type": "invalid_api_key", "message": "Invalid API key" } }
POST/api/v1/generate

Create a generation task

Submits the task to the upstream image provider and immediately returns task_ids. To get the resulting image you can either (A) poll GET /v1/tasks/{id} yourself, or (B) just open the website — the same account's Image Creation tab will auto-pick up the task and persist results to "My Works".

Request

curl -X POST https://www.gencraft.cc/api/v1/generate \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene Japanese garden in autumn",
    "model": "flash",
    "mode": "text",
    "aspect": "16:9",
    "imageSize": "2K",
    "count": 1
  }'

Response

{
  "task_ids": ["task_abc123"],
  "email": "you@example.com"
}

Body parameters

FieldTypeRequiredDefaultDescription
promptstring✓—Generation prompt
modelstringgpt-image-2Model id (see below)
modetext | edit | fusiontexttext=text-to-image; edit=single-image edit; fusion=multi-image blend
aspectstring1:1Ratio: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9, …
imageSize1K | 2K | 4K2KOutput resolution
countnumber1Image count (capped per model)
imageUrlsstring[][]Reference image URLs for edit / fusion

Available models

modelNameSupported modes
gpt-image-2GPT Image 2text, edit
proNano Banana Protext, edit
flash2Nano Banana 2text, edit
flashNano Bananatext, edit

Errors

HTTPerror.typeWhen
400invalid_requestBody is not JSON, prompt is empty, model unknown, or model does not support the mode
401unauthorizedMissing Authorization header or wrong format
401invalid_api_keyAPI key not found in user_keys
500upstream_errorUpstream provider returned an error (message included)
GET/api/v1/tasks/{task_id}

Poll a single task

Returns the upstream task status. status is one of queued / in_progress / completed / failed. completed adds an imageUrl field; failed adds an error field.

Request

curl https://www.gencraft.cc/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "task_id": "task_abc123",
  "status": "completed",
  "progress": 100,
  "imageUrl": "https://files.example.com/generated/xxx.png"
}
GET/api/v1/tasks?ids=t1,t2

Poll multiple tasks

Polls many tasks in one call to save round-trips and auth lookups. Results are returned in the same order as the input ids. Max 20 ids per request.

Request

curl "https://www.gencraft.cc/api/v1/tasks?ids=task_abc,task_def,task_ghi" \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "tasks": [
    { "task_id": "task_abc", "status": "completed", "progress": 100, "imageUrl": "https://..." },
    { "task_id": "task_def", "status": "in_progress", "progress": 60 },
    { "task_id": "task_ghi", "status": "failed", "progress": 0, "error": "model overloaded" }
  ]
}

Polling errors

HTTPerror.typeWhen
400invalid_requestMissing ids param, or more than 20 ids
401unauthorizedMissing Authorization header or wrong format
401invalid_api_keyAPI key not found in user_keys
POST/api/v1/upload

Upload a reference image (for edit / fusion)

Server-side fetches an image from a public URL and re-hosts it on the upstream CDN, returning a stable URL. Pass the result to generate_image's imageUrls. Max 25 MB per image; png / jpeg / webp / gif / bmp accepted.

Request

curl -X POST https://www.gencraft.cc/api/v1/upload \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://example.com/cat.png"}'

Response

{
  "url": "https://files.example.com/uploads/abc123.png",
  "filename": "cat.png",
  "content_type": "image/png",
  "bytes": 524288
}
GET/api/v1/history?page=1&limit=20

List the account's generation history

Returns past generations attributed to this API key, most recent first. Pagination via page (1-indexed) and limit (max 50).

Request

curl "https://www.gencraft.cc/api/v1/history?page=1&limit=20" \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "items": [
    {
      "id": "tsk_img_xxx",
      "prompt": "a cat in autumn",
      "model": "flash",
      "mode": "text",
      "aspect": "16:9",
      "imageSize": "2K",
      "imageCount": 1,
      "images": ["https://..."],
      "refs": [],
      "createdAt": 1777461252000
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}
GET/api/v1/user/status

Get account tier / status

Returns the email, tier (trial / starter / standard / pro), and whether the upstream key is configured. Useful for agents to decide whether they can afford a high-cost model.

Request

curl https://www.gencraft.cc/api/v1/user/status \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "email": "you@example.com",
  "tier": "pro",
  "has_key": true
}

Use via MCP (Claude Desktop / Cursor / Cline)

For LLM agents, the easiest way to use GenCraft is via the official MCP server published as @gencraft/mcp-server on npm. It exposes 6 tools (generate_image, get_task, batch_get_tasks, upload_reference_image, list_my_generations, get_account_status) over stdio and works with any MCP-compatible client. Add the snippet below to your client's MCP config — that's it.

npm · @gencraft/mcp-serverFull README & Cursor / Cline configs →

Claude Desktop config

Path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "gencraft": {
      "command": "npx",
      "args": ["-y", "@gencraft/mcp-server"],
      "env": {
        "GENCRAFT_API_KEY": "<your_api_key>"
      }
    }
  }
}

Notes

  • •Results are automatically attributed to the account that owns this API key — the submitted task is recorded in pending_tasks; when the same account next opens the website's Image Creation tab, the frontend takes over polling, persists results to generations / generation_images, and they appear under "My Works" and the asset library. If you want pure fire-and-forget without showing up in the UI, dedicate a separate caller account.
  • •No server-side rate limiting — your upstream credit balance acts as the natural quota.
  • •Recommended polling interval: 2-5 seconds. Batch endpoint accepts at most 20 ids per call.
  • •Never embed your API key in client-side code. Use it only from your own backend.
© 2026 GenCraft.cc. All rights reserved.