One API. Your choice of model.

Before you begin

Create an account, fund your wallet, and issue an API key in the console. Select a model ID from the authenticated model list; example IDs must be replaced if they are not available to your account.

export PICO_BASE_URL="https://api.picox.ai"
export PICO_API_KEY="YOUR_API_KEY"

Set up with an AI agent

Copy this prompt into your AI agent to configure PicoX, select an available model, and verify the connection.

PicoXhttps://picox.ai

Copy setup prompt

Preview prompt

Configure the AI agent or application in this environment to use PicoX (https://picox.ai) as its model provider. Complete the configuration and verify it.

1. Identify the client, its version, and its actual configuration format. Use its supported custom-provider settings; preserve unrelated settings and back up any file you edit.

2. Set the provider name to PicoX. For OpenAI-compatible clients, set the base URL to https://picox.ai/v1. Use /chat/completions or /responses according to the client's supported API; do not append /v1 twice. For Anthropic-compatible clients, use https://picox.ai as the base URL and /v1/messages as the endpoint.

3. Read the PicoX API key from PICO_API_KEY or the client's secret store. If missing, guide me to create one at https://picox.ai/console/#keys and enter it locally. Do not use a New API Access Token, print the key, or commit it.

4. Query GET https://picox.ai/v1/models with Authorization: Bearer $PICO_API_KEY. Select a model ID from data[].id whose supported_endpoints includes the client's API (chat/completions, responses, or messages); ask me to choose if needed. Do not invent a model ID or copy an upstream channel name.

5. Configure authentication using the client's supported settings: Authorization: Bearer <PICO_API_KEY> for OpenAI-compatible requests, or x-api-key: <PICO_API_KEY> with anthropic-version: 2023-06-01 for Anthropic Messages. Leave the request's provider field and model :supplier suffix unset unless I request a specific supplier; PicoX is the client profile name.

6. Prefer streaming if the client supports it. Run a minimal connection test with the chosen model and report whether authentication, model access, and response handling work.

7. Summarize the files and settings changed, the selected model, and the test result without exposing secrets. If this client cannot use a custom provider, explain the limitation instead of claiming success.

Make your first request

PicoX accepts the SDKs and request formats you already use. Set the PicoX base URL, provide your API key, and choose any model available to your account.

curl "$PICO_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $PICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pico-chat-1",
    "messages": [
      {"role": "user", "content": "Explain vector databases in one sentence."}
    ]
  }'

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["PICO_API_KEY"],
    base_url=os.environ["PICO_BASE_URL"] + "/v1",
)

completion = client.chat.completions.create(
    model="pico-chat-1",
    messages=[{"role": "user", "content": "Explain vector databases in one sentence."}],
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PICO_API_KEY,
  baseURL: `${process.env.PICO_BASE_URL}/v1`,
});

const completion = await client.chat.completions.create({
  model: "pico-chat-1",
  messages: [{ role: "user", content: "Explain vector databases in one sentence." }],
});
console.log(completion.choices[0].message.content);

What comes back

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "pico-chat-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A vector database stores embeddings for similarity search."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 12,
    "total_tokens": 32
  }
}

Authenticate every LLM request with a PicoX key. OpenAI-compatible clients use a Bearer token; Anthropic-compatible clients may use either Bearer authentication or X-API-Key.

New API compatibility

Use the model list to discover the public model IDs available to the authenticated customer. Access policies, customer groups, and the API key's minimum provider discount are applied automatically.

curl "$PICO_BASE_URL/v1/models" \
  -H "Authorization: Bearer $PICO_API_KEY"

Keep your SDK and change the connection settings. OpenAI clients use the /v1 base URL; Anthropic clients use the origin without /v1. Read secrets from environment variables in your server process.

Python

pip install openai anthropic

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PICO_API_KEY"],
    base_url=os.environ["PICO_BASE_URL"].rstrip("/") + "/v1",
    timeout=60.0,
    max_retries=2,
)
result = client.responses.create(model="pico-chat-1", input="Hello!")
print(result.output_text)

Anthropic

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["PICO_API_KEY"],
    base_url=os.environ["PICO_BASE_URL"].rstrip("/"),
)
message = client.messages.create(
    model="pico-chat-1", max_tokens=512,
    messages=[{"role": "user", "content": "Hello!"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)

JavaScript

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PICO_API_KEY,
  baseURL: process.env.PICO_BASE_URL.replace(/\/$/, "") + "/v1",
  timeout: 60_000,
  maxRetries: 2,
});
const result = await client.responses.create({
  model: "pico-chat-1", input: "Hello!",
});
console.log(result.output_text);

Send a conversation as an ordered message list. PicoX routes the public model to its configured provider and converts the request when the upstream uses another supported protocol.

Request parameters

Native routes receive the request body with the model ID replaced. Converted routes receive only the parameters that have an equivalent in the upstream protocol. If no available route accepts a constrained parameter value, PicoX returns 400 parameter_constraint_violation.

{
  "model": "pico-chat-1",
  "messages": [
    {"role": "system", "content": "Answer concisely."},
    {"role": "user", "content": "What is retrieval-augmented generation?"}
  ],
  "temperature": 0.2,
  "stream": false
}

The Responses API provides an item-based output contract for text and function calls. PicoX can convert Responses requests to Chat Completions, Anthropic Messages, or Bedrock Converse and return a Responses-compatible result.

Request parameters

curl "$PICO_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $PICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pico-chat-1",
    "instructions": "You are a precise technical editor.",
    "input": "Rewrite this sentence: APIs makes integrations simple."
  }'

Retrieve a stored response

Responses created with store: true can be retrieved by the same customer.

Use the Anthropic Messages contract with existing Anthropic SDKs. PicoX accepts x-api-key authentication and converts the request to the routed provider protocol when necessary.

Request parameters

curl "$PICO_BASE_URL/v1/messages" \
  -H "X-API-Key: $PICO_API_KEY" \
  -H "Anthropic-Version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pico-chat-1",
    "max_tokens": 512,
    "system": "Answer as a senior engineer.",
    "messages": [{"role": "user", "content": "When should I use a queue?"}]
  }'

Convert text into vectors for semantic search, clustering, recommendations, and retrieval. The selected model must advertise the embeddings capability.

Request parameters

{
  "model": "pico-embedding-1",
  "input": ["First document", "Second document"],
  "dimensions": 256
}

Generate images from a text prompt or edit an existing image through the PicoX API. Both endpoints return a complete JSON response.

Choose an image model

Use your API key to call GET /v1/models and select a model whose supported_endpoints includes images. Replace YOUR_IMAGE_MODEL_ID in the examples with its public ID.

Generate an image

Authenticate with Authorization: Bearer YOUR_API_KEY. Use application/json for text-to-image requests.

Additional model-specific fields are forwarded subject to channel parameter rules. These endpoints are synchronous; stream is removed and no SSE events are returned.

curl "https://picox.ai/v1/images/generations" \
  -H "Authorization: Bearer $PICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "A small glass greenhouse in a quiet garden, soft morning light",
    "n": 1
  }'

Read the image response

A typical successful response contains created and a data array. Each image contains a url or b64_json, depending on the model and requested format. A revised_prompt or usage object may also be present.

{
  "created": 1792972800,
  "data": [
    {"b64_json": "BASE64_ENCODED_IMAGE_DATA"}
  ]
}

Decode b64_json to bytes and save it in the returned image format. When the response contains a URL, download the image promptly because the URL may expire.

Edit an image

For a model that supports editing, send model, prompt, and an image file as multipart/form-data. An optional mask selects the area to edit when supported. File formats, mask rules, and multiple-image support depend on the model.

curl "https://picox.ai/v1/images/edits" \
  -H "Authorization: Bearer $PICO_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL_ID" \
  -F "prompt=Change the background to a sunny garden" \
  -F "[email protected]" \
  -F "n=1"

Let your HTTP client set the multipart Content-Type and boundary. Each request allows at most 16 files and 64 text fields, within the platform request body limit. JSON editing requests are also accepted when supported by the model.

Billing and errors

Generated and edited images are charged at the applicable image output rate per returned image, or per request for request-priced models. Check the model pricing before requesting multiple images; request logs show the final charge.

Errors use the standard PicoX error object. Check error.param for an invalid parameter, verify that the model is available to your API key, and confirm that it supports the requested image operation.

Errors · Usage & billing · Image inputs

Generate videos as asynchronous jobs. The selected model must advertise the videos endpoint; creation is a native passthrough, and status, download, and delete calls always reach the route that created the job.

Create a video

Accepts JSON or multipart/form-data; SDK clients always send multipart. Each request may contain at most 16 files and 64 text fields.

All other JSON fields and form fields are forwarded to the provider unchanged.

curl "$PICO_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $PICO_API_KEY" \
  -F "model=pico-video-1" \
  -F "prompt=A timelapse of a city skyline at dusk" \
  -F "seconds=8" \
  -F "size=1280x720"

{
  "id": "video_abc123",
  "object": "video",
  "status": "queued",
  "model": "pico-video-1",
  "seconds": "8",
  "size": "1280x720",
  "progress": 0,
  "created_at": 1760227200
}

Poll job status

Polls the job on the upstream route that created it; the recorded route means no model parameter is needed and there is no failover. A job owned by another account returns 404 video_not_found, and a route that is no longer available returns 503 video_route_unavailable.

Download the result

Streams the finished media from the creating upstream. Only video/* and image/* content types are relayed; any other type downloads as application/octet-stream.

List your videos

Query parameters

Returns your undeleted jobs in the OpenAI list envelope (data, first_id, last_id, has_more). Each item is the latest upstream snapshot; listing never contacts a provider.

Delete a video

Deletes the job upstream and removes it from your listing. If the upstream already removed it, the job is still deleted and the response reports deleted: true.

Billing

Creation bills the route’s video output price per second when the job reports a duration such as seconds, otherwise per job. Polling, listing, downloading, and deleting are never billed.

Set stream: true to receive Server-Sent Events. PicoX emits the event contract of the endpoint your client called, even when the provider uses a different native protocol.

stream = client.chat.completions.create(
    model="pico-chat-1",
    messages=[{"role": "user", "content": "Write a short launch update."}],
    stream=True,
)

for event in stream:
    if not event.choices:
        continue
    delta = event.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Handle stream boundaries

An HTTP chunk is not necessarily a complete SSE event. Buffer partial data until an event boundary, handle empty choices in usage events, and surface in-stream errors even after HTTP 200.

Provide JSON-schema function definitions with tools. PicoX translates tool definitions, tool choices, calls, and tool-result history across Chat Completions, Responses, Messages, and Bedrock Converse.

{
  "model": "pico-chat-1",
  "messages": [{"role": "user", "content": "What is the weather in Shanghai?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

Complete the tool loop

The model returns a tool call; your application executes the function. Validate arguments, append the assistant tool call and the matching tool result, then request the next response. Never execute untrusted tool arguments without validation.

{
  "role": "tool",
  "tool_call_id": "call_example",
  "content": "{\"temperature_c\":22}"
}

For compatible models, use response_format with Chat Completions or text.format with Responses. PicoX converts JSON Schema settings between the two protocols.

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "support_ticket",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "priority": {"type": "string"},
        "summary": {"type": "string"}
      },
      "required": ["priority", "summary"],
      "additionalProperties": false
    }
  }
}

Choose a model with vision support and a compatible endpoint. In Chat Completions, combine text and image_url blocks inside the user message content array.

Send an image

{
  "model": "YOUR_VISION_MODEL",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/your-image.jpg"
          }
        }
      ]
    }
  ]
}

Input requirements

Replace the example URL with an image accessible to the provider. Accepted image formats, size limits, and detail options depend on the routed model. Do not assume every text model accepts images.

A public model can have several provider routes. Without a selector, PicoX applies your access policy and routing settings to select an eligible route.

Select a provider

Append :provider to a public model ID. The selector matches the provider name, ID, or logo slug in the catalog. Only that supplier remains eligible; it does not bypass model access, discounts, or capability checks.

{
  "model": "openai/gpt-6-astra:azure",
  "messages": [
    {
      "role": "user",
      "content": "Explain routing in one sentence."
    }
  ]
}

Priority and failover

Higher-priority channel tiers are tried first. Channels in the same tier share traffic by weight. If a tier fails, eligible channels in the next tier are attempted. Pinning a supplier limits failover to that supplier.

Unavailable routes

404  provider_route_not_found
503  discount_route_unavailable
400  provider_selector_not_supported

A missing supplier route returns 404. A minimum-discount rule with no eligible route returns 503. Provider selectors cannot be combined with a BYOK connection.

Request rate and concurrent requests are separate limits. A key can stay below its requests-per-minute limit and still exceed its concurrency limit while long streams remain open.

Identify the limit

api_key_rate_limit_exceeded
api_key_concurrency_exceeded
model_rate_limit_exceeded
model_request_rate_limit_exceeded
model_request_success_rate_limit_exceeded

Retry with care

Honor Retry-After when present. Otherwise use bounded exponential backoff with jitter for 429 and transient 5xx failures. Do not repeatedly retry invalid input, expired keys, or exhausted balances.

A timeout can occur after the provider has processed your request. Retrying can repeat work and incur another charge. Set a retry budget, account for SDK retries, and never restart a stream silently after delivering partial output.

Prompt caching depends on the selected model and provider. Repeated prompts do not guarantee a cache hit, and cache read and cache write tokens can have different prices.

Design reusable prefixes

Place stable system instructions, tool definitions, and reference material before changing user content. Keep ordering consistent and check the selected model documentation for cache requirements.

Read the usage breakdown

{
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 80,
    "total_tokens": 1280,
    "prompt_tokens_details": {
      "cached_tokens": 1024
    }
  }
}

Inspect response usage and the console usage ledger. Token counts in this example are illustrative. Cache availability, token reporting, and retention vary by route; a price of zero alone does not prove cache support.

Successful responses include provider-reported input, cache, and output token counts when available. PicoX records the request, selects the lowest applicable price without stacking discounts, and atomically debits both the API key budget and workspace wallet.

Base prices and multipliers

Token prices are listed in USD per million tokens. Resolve the current base and route prices, then compare supplier and account offers against the same reference. Each price component uses the lowest applicable rate; discounts never stack.

Base input:     $4.00 / 1M tokens
Route quote:    $2.00 / 1M tokens
Supplier offer: 10% off base = $3.60
Account offer:  20% off base = $3.20
Final price:    $2.00 / 1M tokens (best offer; no stacking)

Connect New API-compatible tools to your PicoX account to query account information and balance, and manage your own API keys.

Create a management token

1. Open Console → Settings → Account → Access tokens. Open account settings
2. Choose a name, expiration and permissions, then create the token. For key management tools, select both key read and key write permissions.
3. Copy the token and numeric New API user ID. The secret is shown once; you can revoke it from the same settings panel.

Tokens expire after 30 days by default. The console offers 1, 7, 30 or 90 days, or no expiry. The session API accepts 0 for no expiry or 1–366 days. Each account can have 20 active tokens.

Base URL and authentication

Use https://picox.ai as the base URL, without /v1. Send the Access Token as a Bearer token. New-Api-User is optional; if provided, it must match the token owner's numeric user ID.

export PICO_BASE_URL="https://picox.ai"
export PICO_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
export PICO_NEW_API_USER="YOUR_NUMERIC_USER_ID"

Token permissions

Permissions are independent: key write access does not include key read access. A token never grants access to another account.

Supported management endpoints

Use the numeric IDs returned by these endpoints. List and search accept p (default 1) and page_size (default 10, maximum 100); ps and size are aliases. Search uses keyword for names or key prefixes. Trailing slashes are optional.

Request examples

Run the environment setup above first. Replace key ID 123 with the numeric ID returned when listing or creating your key.

curl "$PICO_BASE_URL/api/user/self" \
  -H "Authorization: Bearer $PICO_ACCESS_TOKEN" \
  -H "New-Api-User: $PICO_NEW_API_USER"

curl "$PICO_BASE_URL/api/token/?p=1&page_size=10" \
  -H "Authorization: Bearer $PICO_ACCESS_TOKEN" \
  -H "New-Api-User: $PICO_NEW_API_USER"

curl "$PICO_BASE_URL/api/token/" \
  -H "Authorization: Bearer $PICO_ACCESS_TOKEN" \
  -H "New-Api-User: $PICO_NEW_API_USER" \
  -H "Content-Type: application/json" \
  -d '{"name":"Integration key","remain_quota":5000000,"unlimited_quota":false,"expired_time":-1}'

curl -X PUT "$PICO_BASE_URL/api/token/?status_only=true" \
  -H "Authorization: Bearer $PICO_ACCESS_TOKEN" \
  -H "New-Api-User: $PICO_NEW_API_USER" \
  -H "Content-Type: application/json" \
  -d '{"id":123,"status":2}'

curl -X DELETE "$PICO_BASE_URL/api/token/123" \
  -H "Authorization: Bearer $PICO_ACCESS_TOKEN" \
  -H "New-Api-User: $PICO_NEW_API_USER"

Creation returns the new secret once in data.key. GET responses mask it. Deleting a key invalidates it while retaining usage and accounting history.

Quota units and key settings

• 500,000 quota units equal USD 1. The create example gives the key a USD 10 budget; it does not add funds to the account.
• Account quota is available wallet funds plus unexpired gifts, floored at zero. Credit lines and subscription allowances are not included. used_quota is cumulative recorded spend; request_count is the recorded request count. balance_micros and used_micros provide exact micro-dollar values.
• For finite keys, editing remain_quota sets the remaining budget and preserves past spending. A new finite key requires positive quota. unlimited_quota removes only the key budget cap; account billing policies still apply.
• Set expired_time to Unix seconds, or -1 for no expiry. Status 1 enables a key and 2 disables it. Read responses also use 3 for expired and 4 for exhausted; enabling does not clear these restrictions.
• Edits accept name, status, remain_quota, unlimited_quota, expired_time, model_limits_enabled, model_limits and allow_ips. Omitted fields and native supplier, RPM, concurrency and discount settings are preserved.
• model_limits is a comma-separated list of known model IDs and requires model_limits_enabled=true to enable restrictions. allow_ips accepts IPs or CIDRs separated by commas or newlines; null or an empty string clears IP restrictions. Account access policies still apply.

Responses and compatibility limits

{"success":true,"message":"","data":{"page":1,"page_size":10,"total":0,"items":[]}}

{"success":false,"message":"Access token is missing, invalid, revoked, or expired.","error":"invalid_access_token"}

HTTP 400 indicates invalid fields or an unsupported option, 401 invalid authentication, 403 missing token permission, 404 a missing or unowned key, and 409 a key limit or unavailable secret. Check both HTTP status and success.

This covers personal account and API key management. Administrator endpoints and New API's own token-issuance endpoints are not supported. Cross-group selection, nonempty auto_groups and cross_group_retry=true are rejected. Empty group uses the account's current group.

Existing key secrets cannot be retrieved because only hashes are stored. POST /api/token/{id}/key returns 409 key_secret_unavailable and never silently resets a key. Secret-key search using the token query parameter is also unsupported; use keyword instead.

Balance queries with an API key

Tools that only have a model API key can use the billing endpoints below. Authenticate with an API key, not a management Access Token. The paths also work without the /v1 prefix.

export PICO_API_KEY="YOUR_API_KEY"
curl "$PICO_BASE_URL/v1/dashboard/billing/subscription" \
  -H "Authorization: Bearer $PICO_API_KEY"
curl "$PICO_BASE_URL/v1/dashboard/billing/usage" \
  -H "Authorization: Bearer $PICO_API_KEY"

hard_limit_usd is in USD and total_usage is in US cents. Remaining USD equals hard_limit_usd minus total_usage divided by 100. These results include available gifts and respect the presented key's budget; they do not use the 500,000-unit quota format above.

OpenAI-compatible endpoints return an OpenAI error envelope. The Messages endpoint returns an Anthropic-compatible error envelope. Use the HTTP status and machine-readable code or type for handling.

{
  "error": {
    "message": "Model 'unknown' was not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Move from a working example to a predictable integration with explicit limits, observability, and controlled rollouts.

Protect credentials

Use separate keys for development and production. Set key budgets, expiration, model allowlists, and IP allowlists where appropriate. Rotate a compromised key and remove it from application configuration.

Bound work and latency

Set request timeouts and output-token limits. Bound client concurrency, close streams on cancellation, and combine application retries with SDK retries into one total retry budget.

Observe and validate

Record HTTP status, error code, latency, and X-Request-ID for troubleshooting. Avoid logging secrets or private prompts. Validate model changes with representative requests before rolling them out.

Which model ID should I use?

Use an ID returned by GET /v1/models with your API key. The public catalog helps you compare models, but your account policy determines which models you can call.

Why is a listed model unavailable?

Check the key expiration, model allowlist, customer group, wallet balance, and minimum provider discount. A model also needs an active route that supports the requested endpoint and parameters.

Does a 0.85 multiplier mean 85% off?

No. A 0.85 multiplier means 85% of the base price, or a 15% reduction. Route, supplier and account offers do not stack; the lowest applicable price wins. A minimum provider discount is an eligibility rule.