Generate an image with TokenRoc

Before you begin

• An account and a key. Register in the console, then create a key on the API Keys page. Keep it in a server-side secret or environment variable. Never put it in browser or mobile code.
• Balance. Image requests are charged per image. Top up on the Wallet page if your balance is low.
• A model ID. This guide uses kling/kling-v3-image-generation. Confirm it, and its current price, in Model Square.
• Time. The request stays open while the image is generated, often for a minute or more. Give your HTTP client a timeout of at least 5 minutes.

Set your key once in the terminal you will use:

export TOKENROC_API_KEY="your-api-key"

Send the request

Image generation uses its own route, not /v1/chat/completions. Send JSON with the model ID and a prompt. Model-specific options go inside a parameters object.

curl https://api.tokenroc.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer $TOKENROC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-image-generation",
    "prompt": "A single white ceramic mug on a light oak table, soft morning light, product photo",
    "n": 1,
    "parameters": {
      "resolution": "1k",
      "aspect_ratio": "1:1"
    }
  }'

The same request in Windows PowerShell:

$env:TOKENROC_API_KEY = "your-api-key"

$body = @{
  model      = "kling/kling-v3-image-generation"
  prompt     = "A single white ceramic mug on a light oak table, soft morning light, product photo"
  n          = 1
  parameters = @{ resolution = "1k"; aspect_ratio = "1:1" }
} | ConvertTo-Json -Depth 3

$response = Invoke-RestMethod -Method Post `
  -Uri "https://api.tokenroc.com/v1/images/generations" `
  -Headers @{ Authorization = "Bearer $env:TOKENROC_API_KEY" } `
  -ContentType "application/json" `
  -Body $body `
  -TimeoutSec 300

if ($response.error) { throw $response.error.message }
$response.data[0].url

Request fields

Omni has two more options, described under Choose a model. TokenRoc rejects a field a model does not support instead of ignoring it.

Read the response

There is no task ID to poll. TokenRoc waits for the provider to finish and returns the images in the same response. A successful response looks like this; values are shortened and the signed link is replaced:

{
  "data": [
    {
      "url": "https://<provider-storage>/<image-file>?<signature>",
      "b64_json": "",
      "revised_prompt": ""
    }
  ],
  "created": 1790000000,
  "metadata": {
    "output": { "task_status": "SUCCEEDED", ... },
    "usage": { "image_count": 1, ... },
    ...
  }
}

• data[].url is the image. There is one entry per image, in order, so n: 3 returns three entries.
• created is the Unix time the request started.
• metadata is the provider's own record of the job. usage.image_count is the number of images you are charged for, and it always equals the number of entries in data. Other fields in metadata come from the provider and can change, so do not build on them.

To download it with cURL, paste the URL from data[0].url:

curl -L -o mug.png "PASTE_THE_URL_FROM_data[0].url"

Keep the file extension that appears at the end of the URL path, before the ?.

Choose a model

Both models take the same basic request. Start with the standard model unless you need 4K output or a related series of images.

Omni series mode. Set parameters.result_type to series to get a set of related images from one prompt. Choose how many with parameters.series_amount, from 2 to 9 (default 4). Leave n out in series mode; sending both is rejected.

{
  "model": "kling/kling-v3-omni-image-generation",
  "prompt": "A four-panel story of a cat learning to fish",
  "parameters": {
    "result_type": "series",
    "series_amount": 4,
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }
}

Model availability can change. Copy IDs from Model Square, or list the models your key can use with GET /v1/models.

What it costs

You pay for the images you receive:

cost = images returned (usage.image_count) x price per image x resolution factor

• The resolution factor is 1 for 1K and 2K on both models, and 2 for Omni at 4K.
• Reference images are not charged.
• Your balance must cover the request before it starts. If the request fails, nothing is charged for it.
• Model Square prices are rounded for display, so the amount in your usage log can differ slightly in the last decimal place.

Prices above were checked on 24 September 2026. Model Square always shows the current rate.

Errors and retries

Errors return an error object. The message ends with a request ID, which is the most useful thing to include if you contact support:

{
  "error": {
    "message": "convert image request to ali kling image request failed: kling/kling-v3-image-generation: unsupported resolution \"4k\"; supported values are 1k and 2k (request id: ...)",
    "type": "new_api_error",
    "param": "",
    "code": "convert_request_failed"
  }
}

If your own client times out before TokenRoc responds, you do not receive the images from that request. Raise the client timeout rather than sending many parallel copies. The status page shows whether the TokenRoc gateway is responding. It does not report the health of each individual model.

Check usage

• Usage Logs list each request with its model and charge. Filter by model to find image requests.
• The Wallet page shows your balance and top-ups.
• Model Square shows current per-image prices.

Next steps

• Try the same prompt on kling/kling-v3-omni-image-generation by changing only model.
• Create video from a prompt with the video generation guide.
• Read the API quickstart for text models and the endpoint list.

Stuck? Contact TokenRoc with the model ID, the time of the request, and the request ID from the error message. Never send your API key or a signed image link.