Pluragen — API документация

1. Get Balance

GET /balance

cURL

curl -X GET "https://pluragen.com/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "balance_usd": "124.50"
}

2. Get Models

GET /models

Returns the list of available models, supported media rules, prompt behavior, and model-specific option schema for reseller integration.

Field	Description
`id`	Model ID used when creating orders.
`name`	Human-readable model name.
`type`	General model category such as `image`, `video`, `upscale`, or `remove_bg`.
`price_usd`	Price per generation in USD.
`fields`	Allowed request fields for this model.
`prompt.mode`	Prompt behavior: `required`, `optional`, or `ignored`.
`media.required`	Whether any uploaded media is required.
`media.max_count`	Total maximum number of uploaded files allowed for the model.
`media.accepted`	Allowed media file extensions.
`media.inputs`	List of supported media inputs. Each input contains `key`, `required`, `min`, `max`, and `accepted`.
`options_schema`	List of model-specific options that can be sent inside `options` when creating an order. Each item may include `key`, `type`, `label`, `required`, `default`, `options`, `min`, `max`, `step`, `placeholder`, and `help`.

Example Response

{
  "success": true,
  "models": [
    {
      "id": 20,
      "name": "Nano Banana",
      "type": "image",
      "price_usd": "0.05",
      "fields": ["prompt", "aspect_ratio", "output_format", "media"],
      "prompt": {
        "mode": "required"
      },
      "media": {
        "required": false,
        "max_count": 6,
        "accepted": ["jpg", "jpeg", "png", "webp"],
        "inputs": [
          {
            "key": "image",
            "required": false,
            "min": 0,
            "max": 6,
            "accepted": ["jpg", "jpeg", "png", "webp"]
          }
        ]
      },
      "options_schema": [
        {
          "key": "aspect_ratio",
          "type": "select",
          "label": "Aspect Ratio",
          "required": false,
          "default": "match_input_image",
          "options": [
            { "value": "match_input_image", "label": "match_input_image" },
            { "value": "1:1", "label": "1:1" },
            { "value": "16:9", "label": "16:9" },
            { "value": "9:16", "label": "9:16" }
          ]
        },
        {
          "key": "output_format",
          "type": "select",
          "label": "Output Format",
          "required": false,
          "default": "png",
          "options": [
            { "value": "jpg", "label": "jpg" },
            { "value": "png", "label": "png" }
          ]
        }
      ]
    }
  ]
}

3. Upload File

POST /upload

Upload media first, then use returned tmp_path inside the order request. Some files such as HEIC and HEIF may be processed asynchronously and return processing before they become ready.

cURL

curl -X POST "https://pluragen.com/api/v1/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "file=@/path/to/image.jpg"

Response Example: ready

{
  "success": true,
  "upload": {
    "tmp_path": "tmp/c13d0de5-0795-4c38-b54d-feef2f544b1a",
    "status": "ready",
    "url": "https://pluragen.com/api/v1/upload/preview/c13d0de5-0795-4c38-b54d-feef2f544b1a",
    "original_name": "image.jpg",
    "mime_type": "image/jpeg",
    "size": 2388636,
    "error": null
  }
}

Response Example: processing

{
  "success": true,
  "upload": {
    "tmp_path": "tmp/d81d1ea9-59ec-4223-a489-6b07612020dd",
    "status": "processing",
    "url": null,
    "original_name": "IMG_9508.HEIC",
    "mime_type": "image/heic",
    "size": 3733427,
    "error": null
  }
}

Upload returns a temporary file reference in tmp_path. Use this value in /orders. If upload status is processing, wait until it becomes ready before creating the order. The url field is a temporary authenticated preview URL and should only be used for previewing the uploaded file.

Accepted formats: JPG, JPEG, PNG, WEBP, GIF, HEIC, HEIF, MP4, MOV, WEBM. Maximum file size: 300 MB. Temporary uploads expire after 24 hours. Create the order before expiration.

4. Check Upload Status

GET /upload/status

Check temporary upload status using tmp_path. This is especially useful for HEIC/HEIF files that may require asynchronous conversion before becoming ready.

cURL

curl -G "https://pluragen.com/api/v1/upload/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "tmp_path=tmp/d81d1ea9-59ec-4223-a489-6b07612020dd"

Response

{
  "success": true,
  "upload": {
    "tmp_path": "tmp/d81d1ea9-59ec-4223-a489-6b07612020dd",
    "status": "ready",
    "url": "https://pluragen.com/api/v1/upload/preview/d81d1ea9-59ec-4223-a489-6b07612020dd",
    "original_name": "IMG_9508.HEIC",
    "mime_type": "image/png",
    "size": 22588415,
    "error": null
  }
}

5. Preview Uploaded File

GET /upload/preview/{token}

Returns the uploaded temporary file for preview. This URL requires the same API token used for upload access. Use it only for previewing uploaded media. Use tmp_path when creating orders.

cURL

curl -X GET "https://pluragen.com/api/v1/upload/preview/c13d0de5-0795-4c38-b54d-feef2f544b1a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Preview URLs are temporary and authenticated. They are not intended to be used as permanent public file links.

6. Create Order

POST /orders

Create a generation order using the selected model_id. Use prompt.mode, media.inputs, and options_schema from /models to determine which fields and options are supported for the selected model.

Field	Required	Description
`model_id`	Yes	Model ID from `/models`.
`prompt`	Depends on model	Text prompt. Check `prompt.mode` in `/models`.
`media`	Depends on model	Object keyed by values from `media.inputs[].key`. Each key contains an array of temporary upload paths returned by `/upload`.
`options`	No	Model-specific options. Read supported keys and values from `options_schema` in `/models`.

Headers

Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json
Idempotency-Key: UNIQUE_REQUEST_KEY

Use a unique Idempotency-Key for each new order request. Reusing the same key with the same request data returns the original order. Reusing the same key with different request data returns an idempotency_conflict error. Idempotency keys are scoped per API token.

Request Example: single media input

{
  "model_id": 20,
  "prompt": "ultra realistic portrait of a woman, soft cinematic light",
  "media": {
    "image": ["tmp/c13d0de5-0795-4c38-b54d-feef2f544b1a"]
  },
  "options": {
    "aspect_ratio": "1:1",
    "output_format": "png"
  }
}

Request Example: multi image input

{
  "model_id": 20,
  "prompt": "test multi images",
  "media": {
    "image": [
      "tmp/8eb547bf-5dd7-439e-8b6f-4e7055d2b6cc",
      "tmp/c0432f4e-ade1-4ee2-ae93-78a17db596b1",
      "tmp/8720667b-af67-4615-88f4-275803fe0d20"
    ]
  }
}

Request Example: role-based media

{
  "model_id": 3,
  "prompt": "cinematic portrait",
  "media": {
    "character_image": ["tmp/11111111-2222-3333-4444-555555555555"],
    "target_image": ["tmp/66666666-7777-8888-9999-000000000000"]
  }
}

Request Example: prompt-only model

{
  "model_id": 5,
  "prompt": "a futuristic city at sunset",
  "options": {
    "aspect_ratio": "16:9",
    "output_format": "jpg"
  }
}

Request Example: no prompt required

{
  "model_id": 7,
  "media": {
    "image": ["tmp/c13d0de5-0795-4c38-b54d-feef2f544b1a"]
  },
  "options": {
    "upscale_factor": "x2"
  }
}

Response

{
  "success": true,
  "order": {
    "id": "ord_123",
    "model_id": 20,
    "status": "queued",
    "cost_usd": "0.05",
    "result": [],
    "expires_at": null,
    "error": null
  }
}

Media keys are model-specific. Always read /models first and use the keys returned in media.inputs.

Model-specific generation settings must be sent inside options. Always read options_schema from /models before sending values such as aspect_ratio, output_format, upscale_factor, or other model options.

Orders accept only ready uploads. If a file is still processing, check its state via /upload/status and retry after it becomes ready.

If prompt.mode is ignored, you can omit the prompt field entirely.

7. Get Order

GET /orders/{id}

Returns the current order state, cost, result URLs, expiration time for completed files, and error if generation failed.

Response Example

{
  "success": true,
  "order": {
    "id": "ord_123",
    "model_id": 20,
    "status": "completed",
    "cost_usd": "0.05",
    "result": [
      "https://pluragen.com/g/AbC123xYz..."
    ],
    "expires_at": "2026-04-15T12:00:00Z",
    "error": null
  }
}

Status	Description
`queued`	Order was created and is waiting to start.
`processing`	Generation is in progress.
`completed`	Generation finished successfully.
`failed`	Generation failed.
`cancelled`	Generation was cancelled.

API uses simplified status values. Internal processing states are not exposed.

Result URLs returned inside the order remain stable in the API response. If the generated file expires later, the URL may return 404, but the order response itself does not change.

8. Cancel Order

POST /orders/{id}/cancel

Cancel an active generation order. Only active orders that have already started can be cancelled. Cancellation may take a few seconds to be fully confirmed by the provider. You may need to poll /orders/{id} to get the final status.

cURL

curl -X POST "https://pluragen.com/api/v1/orders/ord_123/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Successful Response

{
  "success": true,
  "order": {
    "id": "ord_123",
    "model_id": 20,
    "status": "cancelled",
    "cost_usd": "0.05",
    "result": [],
    "expires_at": null,
    "error": null
  }
}

Response Example: cannot cancel

{
  "success": false,
  "error": {
    "code": "cannot_cancel",
    "message": "Order cannot be cancelled"
  },
  "order": {
    "id": "ord_123",
    "model_id": 20,
    "status": "completed",
    "cost_usd": "0.05",
    "result": [
      "https://pluragen.com/g/AbC123xYz..."
    ],
    "expires_at": "2026-04-15T12:00:00Z",
    "error": null
  }
}

Response Example: not ready

{
  "success": false,
  "error": {
    "code": "not_ready",
    "message": "Generation not started yet. Try again shortly."
  },
  "order": {
    "id": "ord_123",
    "model_id": 20,
    "status": "queued",
    "cost_usd": "0.05",
    "result": [],
    "expires_at": null,
    "error": null
  }
}

Response Example: cancel pending

{
  "success": false,
  "error": {
    "code": "cancel_pending",
    "message": "Cancellation in progress"
  },
  "order": {
    "id": "ord_123",
    "model_id": 20,
    "status": "processing",
    "cost_usd": "0.05",
    "result": [],
    "expires_at": null,
    "error": null
  }
}

If cancellation is already confirmed, the order status becomes cancelled. If the order is already completed, failed, or otherwise no longer active, the API returns 409.

9. Error Format

Standard Error Response

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request data"
  }
}

Upload-related endpoints may return specific error codes such as upload_processing, file_expired, and file_not_found when a temporary upload is not ready or is no longer available.

Code	Meaning
`unauthorized`	API key missing or invalid.
`model_not_found`	Selected model does not exist or is disabled.
`order_not_found`	Order not found or does not belong to current API key owner.
`cannot_cancel`	The order is already finished or otherwise cannot be cancelled.
`not_ready`	The generation has not started at the provider yet, so cancellation is not available yet.
`cancel_pending`	Cancellation was requested but is not yet confirmed by the provider.
`cancel_failed`	The provider cancellation request failed temporarily.
`file_not_found`	Temporary uploaded file not found.
`file_expired`	Temporary uploaded file expired.
`upload_processing`	Temporary uploaded file is still processing and is not ready to be used in an order yet.
`validation_error`	Request data is invalid or unsupported for the selected model.
`prompt_required`	The selected model requires a prompt.
`media_required`	The selected model requires uploaded media.
`too_many_media`	Too many files were sent for the selected media input.
`invalid_media_type`	Uploaded file type is not supported for the selected model or media input.
`insufficient_balance`	Not enough balance to create the order.
`too_many_active_orders`	You have too many active orders. Wait for some to complete before creating new ones.
`server_busy`	Server is temporarily under high load. Try again shortly.
`idempotency_conflict`	Same idempotency key was already used with different request data.
`internal_error`	Unexpected internal error.

10. HTTP Status Codes

Status	Meaning
`200`	Success.
`201`	Resource created.
`400`	Bad request body or invalid JSON.
`401`	Unauthorized.
`404`	Resource not found.
`422`	Validation or business rule error.
`429`	Too many requests or too many active orders.
`500`	Internal server error.
`503`	Service temporarily unavailable due to high load.