API Documentation

API tokens are authentication credentials that allow programmatic access to Problembo services. Use tokens to integrate our AI services into your applications, scripts, or workflows.

Overview

API tokens are authentication credentials that allow programmatic access to Problembo services. Use tokens to integrate our AI services into your applications, scripts, or workflows.

Getting Started

Creating a Token

Log in to your Problembo account and navigate to the API
Click the "Create Token" button
Enter a descriptive name for your token
Select an expiration period (or set "Never expires")
Click "Create" to generate the token
Important: Copy the token immediately - you won't be able to see it again!

Token Security

Never share tokens with other people
Don't add tokens to version control systems (Git, SVN, etc.)
Use environment variables to store tokens in applications
Regularly rotate tokens for improved security
Revoke compromised tokens immediately

API Usage

Base URL

https://problembo.com/apis/v1/client

Endpoints

POST /apis/v1/client/image-gen/tasks - Create an image generation task
GET /apis/v1/client/tasks/{taskId} - Get task status and result
GET /apis/v1/client/api-contracts/image-gen - Get the current image generation API contract
POST /apis/v1/client/prompt-enhance/image - Synchronously enhance an image prompt
POST /apis/v1/client/prompt-enhance/video - Synchronously enhance video prompts
GET /apis/v1/client/api-contracts/prompt-enhance-image - Get the image prompt enhancement contract
GET /apis/v1/client/api-contracts/prompt-enhance-video - Get the video prompt enhancement contract
POST /apis/v1/client/files/upload-url-for-src - Get a presigned upload URL for a source file via API token
POST /apis/v1/client/files/upload-complete - Confirm a single-part source file upload via API token
POST /apis/v1/client/files/upload-multipart-complete - Confirm a multipart source file upload via API token
POST /apis/v1/client/files/multipart-plan - Get a multipart plan for a source file via API token

Every service accepts POST /apis/v1/client/{contractId}/tasks and returns a taskId. The public contract at GET /apis/v1/client/api-contracts/{contractId} describes the request fields, authentication and response for that service. Contracts do not require a token.

Service	`contractId`
AI photo editor, image extender	`image-edit`
AI image generator, anime generator	`image-gen`
AI video generator	`video-gen`
Photo upscaling and enhancement	`image-upscale`
Video upscaling, FPS boost, stabilize	`video-enhance`
Face swap	`face-swap`
Background removal	`background-removal`
Object removal	`object-removal`
Virtual try-on	`virtual-try-on`
Text to speech	`tts`
Music generation	`music-generation`
Image model (LoRA) training	`train-image`

⚠️ The face swap service (face-swap) is being discontinued: the website no longer accepts face swap tasks, and the API may be shut down after November 10, 2026. To swap a face using a reference photo, use the AI Photo Editor (image-edit contract).

Authentication

Include your API token in the Authorization header of each request:

Authorization: Bearer YOUR_API_TOKEN

Request Structure

Native service endpoints accept a service-specific payload directly. For image generation, send a PrImageGenRequest-compatible body:

{
  "modelId": "waifu-studio-2.6",
  "prompt": "beautiful landscape",
  "imageCount": 1
}

Getting JSON Examples

💡 Important: JSON examples for specific services can be obtained directly in the interface of each service through the "Json for API" button. This is the easiest way to learn the correct request structure for the service you need.

Working with files

If your task needs an input file, see Uploading Source Files for url, fileId, the API-token presigned upload flow, and multipart uploads.

Storage region

By default, Problembo picks the storage for task results by the client IP address. To choose it explicitly, add the optional storageRegion field to the top level of any POST /apis/v1/client/{contractId}/tasks body:

Value	Storage
`auto`	Chosen by client IP (same as omitting it)
`ru`	Storage in Russia
`global`	Storage outside Russia

{
  "modelId": "waifu-studio-2.6",
  "prompt": "beautiful landscape",
  "imageCount": 1,
  "storageRegion": "global"
}

The same field is accepted by POST /apis/v1/client/files/upload-url-for-src for source files. Any other value returns 400 with the PARSE_TASK key. Use global if your requests go through a VPN, proxy, or cloud network and result downloads stall or are slow.

Prompt enhancement

For synchronous image and video prompt enhancement, see the Prompt Enhancement API guide. It covers both payloads, image inputs, pricing, responses, and errors.

Request Examples

Creating an Image Generation Task (POST)

Request:

curl -X POST https://problembo.com/apis/v1/client/image-gen/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "waifu-studio-2.6",
    "prompt": "1girl, beautiful anime character",
    "negativePrompt": "nsfw, low quality",
    "imageCount": 1,
    "aspectRatio": "VERTICAL_16_9"
  }'

Supported aspectRatio values are SQUARE, VERTICAL, HORIZONTAL, VERTICAL_16_9, and HORIZONTAL_16_9. Supported resolution values are 1K, 2K, and 4K; only send a resolution listed for the selected model. Query GET /api/v1/image-gen/catalog?locale=en and use each model's supportedAspectRatios and supportedResolutions. Invalid or unsupported values return 400 without creating or billing a task.

Response (successful creation):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f"
}

Getting Result (GET)

Request:

curl -X GET https://problembo.com/apis/v1/client/tasks/00331b93-31bd-4e33-b28c-cc46793a911f \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response (task in progress):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f",
  "status": "EXECUTING",
  "ready": false
}

Response (task completed successfully):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f",
  "status": "END_SUCCESS",
  "ready": true,
  "completedAt": "2025-11-04T07:14:33Z",
  "result": {
    "taskResult": [
      {
        "origFilename": "problembo-result-20251104071432.jpg",
        "url": "https://prbo.gateway.storjshare.io/910e1b85-4677-49d4-abd3-41218733ab60.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
      }
    ]
  }
}

Response (execution error):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f",
  "status": "END_ERR",
  "ready": true,
  "error": {
    "key": "SD_PROMPT_NOT_SAFE"
  }
}

Task Statuses

A task can be in one of the following statuses:

PENDING - Task created and awaiting processing
ASSIGN_TO_WORKER - Task being assigned to worker
EXECUTING - Task is executing
END_SUCCESS - Task completed successfully
END_ERR - Task completed with error
END_TIMEOUT - Execution timeout exceeded

The ready field indicates whether the task is completed (regardless of result).

Complete Workflow

Typical API workflow scenario:

# 1. Create an image generation task
TASK_ID=$(curl -X POST https://problembo.com/apis/v1/client/image-gen/tasks \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"waifu-studio-2.6","prompt":"beautiful landscape","imageCount":1}' \
  | jq -r '.taskId')

echo "Task ID: $TASK_ID"

# 2. Poll status
while true; do
  RESPONSE=$(curl -s https://problembo.com/apis/v1/client/tasks/$TASK_ID \
    -H "Authorization: Bearer $API_TOKEN")

  STATUS=$(echo $RESPONSE | jq -r '.status')
  READY=$(echo $RESPONSE | jq -r '.ready')

  echo "Status: $STATUS"

  if [ "$READY" = "true" ]; then
    if [ "$STATUS" = "END_SUCCESS" ]; then
      echo "Task completed successfully!"
      echo $RESPONSE | jq '.result'
    else
      echo "Task failed!"
      echo $RESPONSE | jq '.error'
    fi
    break
  fi

  sleep 5
done

Token Management

Token Naming

Give tokens meaningful names to identify their purpose:

production-server
development-testing
mobile-app-v2

Expiration Settings

Choose appropriate expiration based on your use case:

30 days: Testing and development
90 days: Short-term projects
1 year: Long-term applications
Never expires: Critical infrastructure (rotate manually)

Token Status

Tokens can have the following statuses:

Active: Token is valid and can be used
Disabled: Temporarily disabled, can be re-enabled
Expired: Expiration period passed, cannot be used
Revoked: Permanently invalidated

Rate Limiting

API uses distributed rate limiting to protect against overload:

Endpoint Limits

Status polling (GET /apis/v1/client/tasks/{id}, GET /apis/v1/client/operations/{id}): 120 requests per minute per API token
API contract descriptions (/apis/v1/client/api-contracts/**): 300 requests per minute per IP
All other /apis/v1/client/** endpoints (task submission, file uploads, prompt enhancement): a shared limit of 60 requests per minute per API token, plus an independent limit of 120 requests per minute per IP

Rate Limit Response

When you exceed the limit, you'll receive HTTP status 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded"
}

The Retry-After header indicates how many seconds to wait before retrying.

Error Codes

HTTP Status Codes

200 OK - Request processed successfully
400 Bad Request - Invalid request or validation error
401 Unauthorized - Invalid or missing token
403 Forbidden - The selected model is not available to your account
404 Not Found - Task not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Internal server error
503 Service Unavailable - The service is temporarily overloaded; retry the request later

Task submission errors with status 400, 403, or 503 use the standard Client API envelope: the machine-readable error code is in errorKey, and the user-facing text, when present, is in message.

Task Error Codes (error.key)

When task execution fails, the response contains an error object whose key is one of these codes:

Access and Billing Errors

BILLING_ACCESS_DENIED - Insufficient balance
IP_BILLING_ACCESS_DENIED - IP address blocked
IP_BAN - IP address banned
ANONYMOUS_USER - Authentication required
NOT_PAID_USER - Feature available only to paid users

Validation Errors

PARSE_TASK - JSON request parsing error
INVALID_INPUT_FILE - Invalid input file
SD_EMPTY_PROMPT - Empty prompt
SD_PROMPT_TOO_LONG - Prompt too long
SD_NO_LATIN_PROMPT - Prompt must be in Latin characters
SD_PROMPT_NOT_SAFE - Prompt contains unsafe content

Limits

MAX_PARALLEL_TASKS_PER_IP - Parallel tasks per IP limit exceeded
MAX_TASKS_PER_USER - User tasks limit exceeded

System Errors

SERVICE_DISABLED - Service temporarily disabled
MAINTENANCE - Maintenance in progress
BUSY - System overloaded
TIMEOUT - Task execution timeout exceeded
NOT_FOUND - Task not found
UNKNOWN_ERROR - Unknown error

Best Practices

Use separate tokens for different applications or environments
Set appropriate expiration periods for your use case
Implement polling with reasonable intervals (3-5 seconds recommended)
Handle all possible task statuses in your code
Implement retry logic with exponential backoff for rate limiting
Check balance before sending large numbers of tasks
Cache results when possible to avoid redundant requests
Handle errors gracefully - log error.key for debugging
Monitor token usage in the statistics section

Troubleshooting

Token Not Working

Ensure the token is active and not expired
Check the header format is correct: Authorization: Bearer TOKEN
Ensure the account has sufficient credits
Check that the token starts with prefix pbo_pat_

401 Unauthorized Error

Possible causes:

Token is invalid, expired, or revoked
Incorrect Authorization header format
Extra spaces or characters in token
Token not copied completely

Solution:

# Correct
curl -H "Authorization: Bearer pbo_pat_..."

# Incorrect
curl -H "Authorization: pbo_pat_..."  # missing "Bearer"
curl -H "Authorization: Bearer  pbo_pat_..."  # double space

429 Too Many Requests Error

You've exceeded the rate limit.

Solution:

Wait for the time specified in Retry-After header
Implement exponential backoff between retries
Optimize task status polling frequency
Use batching for bulk operations

BILLING_ACCESS_DENIED Error

Insufficient balance.

Solution:

Check balance in your account
Top up balance
Ensure correct pricing plan is selected

SD_PROMPT_NOT_SAFE Error

Prompt contains unsafe or prohibited content.

Solution:

Check prompt for prohibited words
Use more neutral phrasing
Contact support if you believe the prompt is appropriate

Task Stuck in EXECUTING Status

Task is taking longer than usual.

Solution:

Continue polling status - some tasks can take 5-10 minutes
Check system status on monitoring page
If task doesn't complete after 15 minutes, contact support with taskId

Result Download Stalls or Times Out

The task is END_SUCCESS, but downloading the result url stops partway or times out. This usually happens on network routes between your client and the selected storage, for example when traffic goes through a VPN, proxy, or cloud network.

Solution:

Submit new tasks with "storageRegion": "global" (see )
Pass the same field when uploading source files via upload-url-for-src
If downloads still fail, contact support with the taskId

Examples in Other Languages

JavaScript/TypeScript

const API_TOKEN = 'pbo_pat_your_token'
const SUBMIT_URL = 'https://problembo.com/apis/v1/client/image-gen/tasks'
const TASKS_URL = 'https://problembo.com/apis/v1/client/tasks'

const headers = {
  Authorization: `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json',
}

// Create task
async function createTask() {
  const response = await fetch(SUBMIT_URL, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      modelId: 'waifu-studio-2.6',
      prompt: 'beautiful landscape',
      imageCount: 1,
    }),
  })

  const data = await response.json()
  return data.taskId
}

// Poll status
async function waitForTask(taskId: string) {
  while (true) {
    const response = await fetch(`${TASKS_URL}/${taskId}`, { headers })
    const data = await response.json()

    console.log(`Status: ${data.status}`)

    if (data.ready) {
      return data
    }

    await new Promise(resolve => setTimeout(resolve, 5000))
  }
}

// Usage
const taskId = await createTask()
console.log(`Task created: ${taskId}`)

const result = await waitForTask(taskId)
if (result.status === 'END_SUCCESS') {
  console.log('Success!', result.result)
} else {
  console.log('Failed!', result.error)
}

Support

Need help? Contact our support team:

Email: support@problembo.com
Telegram: @problembo_support

Last updated: October 13, 2026

Home

Problembo documentation: guides, tutorials, and practical instructions for chat, image editing, face swap, model training, and other AI services.

Uploading Source Files

How to upload source files to Problembo File Store and use them in API tasks via `fileId` or direct `url`.