Skip to Content

Development Guide

Integrate the API into your application.

This guide helps you integrate 123API into your application with a production-friendly request flow.

Asynchronous Processing

Image and video endpoints commonly use an asynchronous processing model:

  1. Submit a task and receive a task ID
  2. Poll status at a steady interval
  3. Retrieve the generation result when the task completes

Polling example

import time
import requests
 
 
def wait_for_completion(task_id, api_key, max_wait=300):
    start_time = time.time()
 
    while time.time() - start_time < max_wait:
        response = requests.get(
            f"https://123api.co/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        result = response.json()
 
        if result.get("status") == "completed":
            return result
        if result.get("status") == "failed":
            raise RuntimeError(result.get("error", "task failed"))
 
        time.sleep(2)
 
    raise TimeoutError("task timeout")

Error Handling

Common errors

StatusDescriptionResolution
400Invalid request parametersCheck request parameters and format
401Authentication failedVerify your API key
402Insufficient balanceRecharge or switch to a supported project key
429Rate limit exceededReduce request frequency and add retries
500Server errorRetry later with exponential backoff

Example

try:
    response = requests.post(
        "https://123api.co/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
        json=payload,
        timeout=60
    )
    response.raise_for_status()
except requests.HTTPError as exc:
    if exc.response.status_code == 401:
        print("Invalid API key")
    elif exc.response.status_code == 402:
        print("Insufficient account balance")
    else:
        print(f"Request failed: {exc.response.text}")

Best Practices

  1. Cache generated image and video links on your own storage when needed
  2. Implement retries with exponential backoff on transient errors
  3. Monitor API usage and model-level traffic separately
  4. Keep your API key on the server side whenever possible

Support

If you run into issues during development: