curl

curl https://api.naga.ac/v1/images/generations \
  -H "Authorization: Bearer $NAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-1",
  "prompt": "A watercolour fox in a snowy forest",
  "size": "1024x1024",
  "n": 1
}'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NAGA_API_KEY"],
    base_url="https://api.naga.ac/v1",
)

result = client.images.generate(
    model="gpt-image-1",
    prompt="A watercolour fox in a snowy forest",
    size="1024x1024",
    n=1,
)
print(result)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NAGA_API_KEY,
  baseURL: "https://api.naga.ac/v1",
});

const result = await client.images.generate({
  model: "gpt-image-1",
  prompt: "A watercolour fox in a snowy forest",
  size: "1024x1024",
  n: 1,
});
console.log(result);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.naga.ac/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"gpt-image-1\",\n  \"prompt\": \"A watercolour fox in a snowy forest\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "created": 1774000000,
  "data": [
    {
      "url": "https://cdn.naga.ac/images/9f2c4a1b.png"
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 1024,
    "total_tokens": 1036
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "invalid_api_key",
    "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again."
  }
}

{
  "error": {
    "type": "insufficient_quota",
    "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits."
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit reached. Please try again in 3s."
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Images

Create an image

Creates images from a text prompt. The response carries one entry per produced image, each holding either a link the gateway hosts or the image bytes inline.

Requires an API key.

model names a model from Naga’s catalog that serves images.generations, and the gateway selects a provider for it.

Three checks run before a provider is called.

The prompt is screened by Naga’s own moderation. A flagged prompt returns 403 inappropriate_content, naming the categories that fired, and no provider is called.
size is checked for shape alone: two runs of digits with an x between them. Whether the model can produce that size is the provider’s answer.
n is checked against the maximum the selected model declares for itself, where it declares one.

response_format selects which field of every data[] entry is filled. Exactly one of the two is present on each entry.

url, the default — the gateway stores the bytes the provider returned in its own object store under a freshly minted random name, and responds with the public URL of that copy. The link belongs to Naga and points at the stored copy. The object carries no expiry.
b64_json — the image bytes inline, as standard base64. The gateway stores nothing, so the response carries no link to return to later.

The account is charged after the images are delivered, at the model’s published prices. usage on the response is the gateway’s own count and is the same count the charge is computed from. Models that price a prompt count it in input tokens. Produced images are counted in output tokens, using the provider’s number where it reported one and a flat 2048 per image where it did not. A request whose images could not be delivered is not charged.

Every response below 200 carries an object under error with a machine-readable type, a human-readable message, and, where the failure concerns one field, param. 429 and 503 carry Retry-After with the seconds to wait.

POST

images

generations

curl

curl https://api.naga.ac/v1/images/generations \
  -H "Authorization: Bearer $NAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-1",
  "prompt": "A watercolour fox in a snowy forest",
  "size": "1024x1024",
  "n": 1
}'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NAGA_API_KEY"],
    base_url="https://api.naga.ac/v1",
)

result = client.images.generate(
    model="gpt-image-1",
    prompt="A watercolour fox in a snowy forest",
    size="1024x1024",
    n=1,
)
print(result)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NAGA_API_KEY,
  baseURL: "https://api.naga.ac/v1",
});

const result = await client.images.generate({
  model: "gpt-image-1",
  prompt: "A watercolour fox in a snowy forest",
  size: "1024x1024",
  n: 1,
});
console.log(result);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.naga.ac/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"gpt-image-1\",\n  \"prompt\": \"A watercolour fox in a snowy forest\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "created": 1774000000,
  "data": [
    {
      "url": "https://cdn.naga.ac/images/9f2c4a1b.png"
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 1024,
    "total_tokens": 1036
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "invalid_api_key",
    "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again."
  }
}

{
  "error": {
    "type": "insufficient_quota",
    "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits."
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit reached. Please try again in 3s."
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

An account API key. Send it as Authorization: Bearer <key>.

Body

application/json

The request body of POST /v1/images/generations.

POST /v1/images/edits asks for the same six fields as multipart form parts instead, beside the image files themselves, an optional mask and an optional background. Its prompt is bounded at 32000 characters rather than at 8192.

model

string

required

The model to generate with, named by its id or by one of its aliases. A name this gateway does not serve on this route is refused with 400 model_not_found; a name it served and has since retired, with 410 model_deprecated.

prompt

string

required

What to generate, in words. One to 8192 characters — characters, not bytes. The prompt is screened by the gateway's own moderation before the image model is called, and a flagged prompt is refused with 403 inappropriate_content naming the categories that fired.

quality

string | null

The provider's quality knob, passed through untouched. The gateway neither checks the value nor holds a menu of accepted ones. What a value means is the serving provider's business, and a provider with no such knob drops it.

size

string | null

The requested image size, written {width}x{height}, as in 1024x1024. The gateway checks the shape alone: two runs of decimal digits with an x between them. Any other shape is refused with 400. Whether the model can produce that particular size is the provider's answer.

integer<int64> | null

How many images to ask for. Absent means one. Less than 1 is refused with 400, and so is a value above the maximum a model declares for itself. How many images actually come back is the provider's answer — data carries what it produced.

response_format

enum<string>

Whether each image comes back as a link (url) or as inline base64 (b64_json). url when the key is absent, and the choice is what decides which field of every data[] entry is filled.

Available options:

url,

b64_json

Response

The produced images. Each entry of data carries either a link the gateway hosts or the bytes inline, whichever response_format asked for. usage carries the count the charge was computed from.

The body of a successful POST /v1/images/generations and of POST /v1/images/edits — one shape, answered by both routes.

created

integer<int64>

required

When the gateway rendered this body, in whole seconds since the Unix epoch. The clock is read after the provider has answered, so the value dates the answer rather than the request.

data

object[]

required

The produced images, in the order the provider returned them — one entry per image it produced, which need not be the n that was asked for.

Hide child attributes

data.url

string | null

A link to the image, sent when response_format was url. The gateway stores the bytes the provider returned in its own object store, under a freshly minted random name, and answers with the public URL of that copy. The link is Naga's own and never points at the provider. No expiry is set when the object is written. A deployment that configures no public base URL for that store answers the bare storage key here instead of an absolute URL.

data.b64_json

string | null

The image bytes themselves, standard base64, sent when response_format was b64_json. Nothing is stored on this branch, so there is no link to come back to later.

usage

object

required

What the request was metered on. Always present, including for a provider that reports no usage of its own: the gateway fills the block from its own counting.

Hide child attributes

usage.output_tokens

integer<int64>

required

Output tokens charged for the produced images. The provider's own count when it reported one; when it did not, a flat 2048 per returned image, which is the deterministic local count this capability bills on.

usage.total_tokens

integer<int64>

required

The sum of input_tokens and output_tokens.

usage.input_tokens

integer<int64> | null

Input tokens charged for. Zero whenever the model carries no price per input text token — the prompt is not counted at all in that case, so the zero says nothing about the prompt itself. Where the model does price them it is the provider's own count when the provider reported one, and the gateway's tokenization of the prompt when it did not. On /v1/images/edits the input images fold into this same number, again only for a model that prices them. Always present in a body this gateway sends.

Overview

Endpoints

Create an image

Authorizations

Body

Response