@runapi.ai/nano-banana 0.2.1 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/index.d.mts +20 -24
- package/dist/index.d.ts +20 -24
- package/package.json +3 -10
- package/skills/nano-banana/README.md +36 -4
- package/skills/nano-banana/SKILL.md +52 -179
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Nano Banana API JavaScript SDK for RunAPI
|
|
2
2
|
|
|
3
|
-
The nano banana api JavaScript SDK is the language-specific package for Nano Banana on RunAPI. Use this nano banana api package for text-to-image, image
|
|
3
|
+
The nano banana api JavaScript SDK is the language-specific package for Nano Banana on RunAPI. Use this nano banana api package for text-to-image, image editing, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in JavaScript.
|
|
4
4
|
|
|
5
5
|
This nano banana api README is the JavaScript package guide inside the public `nano-banana-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/nano-banana; for API reference, use https://runapi.ai/docs#nano-banana; for SDK docs, use https://runapi.ai/docs#sdk-nano-banana.
|
|
6
6
|
|
package/dist/index.d.mts
CHANGED
|
@@ -3,30 +3,22 @@ export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundEr
|
|
|
3
3
|
|
|
4
4
|
type TextToImageModel = 'nano-banana' | 'nano-banana-pro' | 'nano-banana-2';
|
|
5
5
|
type EditImageModel = 'nano-banana-edit';
|
|
6
|
-
|
|
7
|
-
* Base model aspect ratio options.
|
|
8
|
-
* Note: Base model uses 'image_size' parameter which includes 'auto' option.
|
|
9
|
-
*/
|
|
10
|
-
type ImageSize = '1:1' | '9:16' | '16:9' | '3:4' | '4:3' | '3:2' | '2:3' | '5:4' | '4:5' | '21:9' | 'auto';
|
|
11
|
-
/**
|
|
12
|
-
* Pro model aspect ratio options.
|
|
13
|
-
* Note: Pro model uses 'aspect_ratio' parameter (includes 'auto' option).
|
|
14
|
-
*/
|
|
6
|
+
type BaseAspectRatio = '1:1' | '9:16' | '16:9' | '3:4' | '4:3' | '3:2' | '2:3' | '5:4' | '4:5' | '21:9' | 'auto';
|
|
15
7
|
type AspectRatio = '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9' | 'auto';
|
|
16
8
|
/**
|
|
17
9
|
* V2 model aspect ratio options. Superset of Pro, adding extreme ratios
|
|
18
10
|
* (1:4, 1:8, 4:1, 8:1). Default is 'auto'.
|
|
19
11
|
*/
|
|
20
12
|
type AspectRatioV2 = AspectRatio | '1:4' | '1:8' | '4:1' | '8:1';
|
|
21
|
-
type
|
|
13
|
+
type OutputResolution = '1k' | '2k' | '4k';
|
|
22
14
|
type OutputFormat = 'png' | 'jpg' | 'jpeg';
|
|
23
15
|
interface GenerationBaseParams {
|
|
24
16
|
model: 'nano-banana';
|
|
25
17
|
prompt: string;
|
|
26
18
|
callback_url?: string;
|
|
27
19
|
output_format?: OutputFormat;
|
|
28
|
-
|
|
29
|
-
|
|
20
|
+
aspect_ratio?: BaseAspectRatio;
|
|
21
|
+
reference_image_urls?: string[];
|
|
30
22
|
}
|
|
31
23
|
interface GenerationProParams {
|
|
32
24
|
model: 'nano-banana-pro';
|
|
@@ -34,8 +26,8 @@ interface GenerationProParams {
|
|
|
34
26
|
callback_url?: string;
|
|
35
27
|
output_format?: OutputFormat;
|
|
36
28
|
aspect_ratio?: AspectRatio;
|
|
37
|
-
|
|
38
|
-
|
|
29
|
+
output_resolution?: OutputResolution;
|
|
30
|
+
reference_image_urls?: string[];
|
|
39
31
|
}
|
|
40
32
|
interface GenerationV2Params {
|
|
41
33
|
model: 'nano-banana-2';
|
|
@@ -43,47 +35,51 @@ interface GenerationV2Params {
|
|
|
43
35
|
callback_url?: string;
|
|
44
36
|
output_format?: OutputFormat;
|
|
45
37
|
aspect_ratio?: AspectRatioV2;
|
|
46
|
-
|
|
47
|
-
|
|
38
|
+
output_resolution?: OutputResolution;
|
|
39
|
+
reference_image_urls?: string[];
|
|
48
40
|
}
|
|
49
41
|
type TextToImageParams = GenerationBaseParams | GenerationProParams | GenerationV2Params;
|
|
50
42
|
interface EditImageParams {
|
|
51
43
|
model: 'nano-banana-edit';
|
|
52
44
|
prompt: string;
|
|
53
|
-
|
|
45
|
+
source_image_urls: string[];
|
|
54
46
|
callback_url?: string;
|
|
55
47
|
output_format?: OutputFormat;
|
|
56
|
-
|
|
48
|
+
aspect_ratio?: BaseAspectRatio;
|
|
57
49
|
}
|
|
58
50
|
interface TaskCreateResponse {
|
|
59
51
|
id: string;
|
|
60
52
|
}
|
|
53
|
+
interface Image {
|
|
54
|
+
url: string;
|
|
55
|
+
origin_url?: string;
|
|
56
|
+
}
|
|
61
57
|
interface TextToImageResponse {
|
|
62
58
|
id: string;
|
|
63
59
|
status: AsyncTaskStatus;
|
|
64
|
-
|
|
60
|
+
images?: Image[];
|
|
65
61
|
error?: string;
|
|
66
62
|
[key: string]: unknown;
|
|
67
63
|
}
|
|
68
64
|
interface EditImageResponse {
|
|
69
65
|
id: string;
|
|
70
66
|
status: AsyncTaskStatus;
|
|
71
|
-
|
|
67
|
+
images?: Image[];
|
|
72
68
|
error?: string;
|
|
73
69
|
[key: string]: unknown;
|
|
74
70
|
}
|
|
75
71
|
/**
|
|
76
72
|
* Resolved responses returned by the `run()` methods after polling sees
|
|
77
|
-
* `status: 'completed'`. Narrows the base response so `
|
|
73
|
+
* `status: 'completed'`. Narrows the base response so `images` is
|
|
78
74
|
* guaranteed non-optional in user code.
|
|
79
75
|
*/
|
|
80
76
|
type CompletedTextToImageResponse = TextToImageResponse & {
|
|
81
77
|
status: 'completed';
|
|
82
|
-
|
|
78
|
+
images: Image[];
|
|
83
79
|
};
|
|
84
80
|
type CompletedEditImageResponse = EditImageResponse & {
|
|
85
81
|
status: 'completed';
|
|
86
|
-
|
|
82
|
+
images: Image[];
|
|
87
83
|
};
|
|
88
84
|
|
|
89
85
|
declare class TextToImage {
|
|
@@ -126,4 +122,4 @@ declare class NanoBananaClient {
|
|
|
126
122
|
constructor(options?: ClientOptions);
|
|
127
123
|
}
|
|
128
124
|
|
|
129
|
-
export { type AspectRatio, type AspectRatioV2, type CompletedEditImageResponse, type CompletedTextToImageResponse, type EditImageModel, type EditImageParams, type EditImageResponse, type GenerationBaseParams, type GenerationProParams, type GenerationV2Params, type
|
|
125
|
+
export { type AspectRatio, type AspectRatioV2, type BaseAspectRatio, type CompletedEditImageResponse, type CompletedTextToImageResponse, type EditImageModel, type EditImageParams, type EditImageResponse, type GenerationBaseParams, type GenerationProParams, type GenerationV2Params, type Image, NanoBananaClient, type OutputFormat, type OutputResolution, type TaskCreateResponse, type TextToImageModel, type TextToImageParams, type TextToImageResponse };
|
package/dist/index.d.ts
CHANGED
|
@@ -3,30 +3,22 @@ export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundEr
|
|
|
3
3
|
|
|
4
4
|
type TextToImageModel = 'nano-banana' | 'nano-banana-pro' | 'nano-banana-2';
|
|
5
5
|
type EditImageModel = 'nano-banana-edit';
|
|
6
|
-
|
|
7
|
-
* Base model aspect ratio options.
|
|
8
|
-
* Note: Base model uses 'image_size' parameter which includes 'auto' option.
|
|
9
|
-
*/
|
|
10
|
-
type ImageSize = '1:1' | '9:16' | '16:9' | '3:4' | '4:3' | '3:2' | '2:3' | '5:4' | '4:5' | '21:9' | 'auto';
|
|
11
|
-
/**
|
|
12
|
-
* Pro model aspect ratio options.
|
|
13
|
-
* Note: Pro model uses 'aspect_ratio' parameter (includes 'auto' option).
|
|
14
|
-
*/
|
|
6
|
+
type BaseAspectRatio = '1:1' | '9:16' | '16:9' | '3:4' | '4:3' | '3:2' | '2:3' | '5:4' | '4:5' | '21:9' | 'auto';
|
|
15
7
|
type AspectRatio = '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9' | 'auto';
|
|
16
8
|
/**
|
|
17
9
|
* V2 model aspect ratio options. Superset of Pro, adding extreme ratios
|
|
18
10
|
* (1:4, 1:8, 4:1, 8:1). Default is 'auto'.
|
|
19
11
|
*/
|
|
20
12
|
type AspectRatioV2 = AspectRatio | '1:4' | '1:8' | '4:1' | '8:1';
|
|
21
|
-
type
|
|
13
|
+
type OutputResolution = '1k' | '2k' | '4k';
|
|
22
14
|
type OutputFormat = 'png' | 'jpg' | 'jpeg';
|
|
23
15
|
interface GenerationBaseParams {
|
|
24
16
|
model: 'nano-banana';
|
|
25
17
|
prompt: string;
|
|
26
18
|
callback_url?: string;
|
|
27
19
|
output_format?: OutputFormat;
|
|
28
|
-
|
|
29
|
-
|
|
20
|
+
aspect_ratio?: BaseAspectRatio;
|
|
21
|
+
reference_image_urls?: string[];
|
|
30
22
|
}
|
|
31
23
|
interface GenerationProParams {
|
|
32
24
|
model: 'nano-banana-pro';
|
|
@@ -34,8 +26,8 @@ interface GenerationProParams {
|
|
|
34
26
|
callback_url?: string;
|
|
35
27
|
output_format?: OutputFormat;
|
|
36
28
|
aspect_ratio?: AspectRatio;
|
|
37
|
-
|
|
38
|
-
|
|
29
|
+
output_resolution?: OutputResolution;
|
|
30
|
+
reference_image_urls?: string[];
|
|
39
31
|
}
|
|
40
32
|
interface GenerationV2Params {
|
|
41
33
|
model: 'nano-banana-2';
|
|
@@ -43,47 +35,51 @@ interface GenerationV2Params {
|
|
|
43
35
|
callback_url?: string;
|
|
44
36
|
output_format?: OutputFormat;
|
|
45
37
|
aspect_ratio?: AspectRatioV2;
|
|
46
|
-
|
|
47
|
-
|
|
38
|
+
output_resolution?: OutputResolution;
|
|
39
|
+
reference_image_urls?: string[];
|
|
48
40
|
}
|
|
49
41
|
type TextToImageParams = GenerationBaseParams | GenerationProParams | GenerationV2Params;
|
|
50
42
|
interface EditImageParams {
|
|
51
43
|
model: 'nano-banana-edit';
|
|
52
44
|
prompt: string;
|
|
53
|
-
|
|
45
|
+
source_image_urls: string[];
|
|
54
46
|
callback_url?: string;
|
|
55
47
|
output_format?: OutputFormat;
|
|
56
|
-
|
|
48
|
+
aspect_ratio?: BaseAspectRatio;
|
|
57
49
|
}
|
|
58
50
|
interface TaskCreateResponse {
|
|
59
51
|
id: string;
|
|
60
52
|
}
|
|
53
|
+
interface Image {
|
|
54
|
+
url: string;
|
|
55
|
+
origin_url?: string;
|
|
56
|
+
}
|
|
61
57
|
interface TextToImageResponse {
|
|
62
58
|
id: string;
|
|
63
59
|
status: AsyncTaskStatus;
|
|
64
|
-
|
|
60
|
+
images?: Image[];
|
|
65
61
|
error?: string;
|
|
66
62
|
[key: string]: unknown;
|
|
67
63
|
}
|
|
68
64
|
interface EditImageResponse {
|
|
69
65
|
id: string;
|
|
70
66
|
status: AsyncTaskStatus;
|
|
71
|
-
|
|
67
|
+
images?: Image[];
|
|
72
68
|
error?: string;
|
|
73
69
|
[key: string]: unknown;
|
|
74
70
|
}
|
|
75
71
|
/**
|
|
76
72
|
* Resolved responses returned by the `run()` methods after polling sees
|
|
77
|
-
* `status: 'completed'`. Narrows the base response so `
|
|
73
|
+
* `status: 'completed'`. Narrows the base response so `images` is
|
|
78
74
|
* guaranteed non-optional in user code.
|
|
79
75
|
*/
|
|
80
76
|
type CompletedTextToImageResponse = TextToImageResponse & {
|
|
81
77
|
status: 'completed';
|
|
82
|
-
|
|
78
|
+
images: Image[];
|
|
83
79
|
};
|
|
84
80
|
type CompletedEditImageResponse = EditImageResponse & {
|
|
85
81
|
status: 'completed';
|
|
86
|
-
|
|
82
|
+
images: Image[];
|
|
87
83
|
};
|
|
88
84
|
|
|
89
85
|
declare class TextToImage {
|
|
@@ -126,4 +122,4 @@ declare class NanoBananaClient {
|
|
|
126
122
|
constructor(options?: ClientOptions);
|
|
127
123
|
}
|
|
128
124
|
|
|
129
|
-
export { type AspectRatio, type AspectRatioV2, type CompletedEditImageResponse, type CompletedTextToImageResponse, type EditImageModel, type EditImageParams, type EditImageResponse, type GenerationBaseParams, type GenerationProParams, type GenerationV2Params, type
|
|
125
|
+
export { type AspectRatio, type AspectRatioV2, type BaseAspectRatio, type CompletedEditImageResponse, type CompletedTextToImageResponse, type EditImageModel, type EditImageParams, type EditImageResponse, type GenerationBaseParams, type GenerationProParams, type GenerationV2Params, type Image, NanoBananaClient, type OutputFormat, type OutputResolution, type TaskCreateResponse, type TextToImageModel, type TextToImageParams, type TextToImageResponse };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runapi.ai/nano-banana",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.5",
|
|
4
4
|
"description": "RunAPI Nano Banana SDK for JavaScript, Ruby, and Go",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -25,17 +25,10 @@
|
|
|
25
25
|
"build": "tsup",
|
|
26
26
|
"test": "vitest run",
|
|
27
27
|
"typecheck": "tsc --noEmit",
|
|
28
|
-
"clean": "rm -rf dist"
|
|
29
|
-
"test:base": "dotenv -e manual-tests/.env -- tsx manual-tests/test-generation-base.ts",
|
|
30
|
-
"test:pro": "dotenv -e manual-tests/.env -- tsx manual-tests/test-generation-pro.ts",
|
|
31
|
-
"test:edit": "dotenv -e manual-tests/.env -- tsx manual-tests/test-edit.ts",
|
|
32
|
-
"test:polling": "dotenv -e manual-tests/.env -- tsx manual-tests/test-polling.ts",
|
|
33
|
-
"test:errors": "dotenv -e manual-tests/.env -- tsx manual-tests/test-error-handling.ts",
|
|
34
|
-
"test:all": "dotenv -e manual-tests/.env -- tsx manual-tests/test-all.ts",
|
|
35
|
-
"test:manual": "pnpm run test:all"
|
|
28
|
+
"clean": "rm -rf dist"
|
|
36
29
|
},
|
|
37
30
|
"dependencies": {
|
|
38
|
-
"@runapi.ai/core": "^0.2.
|
|
31
|
+
"@runapi.ai/core": "^0.2.5"
|
|
39
32
|
},
|
|
40
33
|
"devDependencies": {
|
|
41
34
|
"@types/node": "^20.0.0",
|
|
@@ -1,4 +1,25 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/runapi-ai/nano-banana">
|
|
3
|
+
<h3 align="center">Nano Banana API Skill for RunAPI</h3>
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
Install this agent skill, inspect Nano Banana fields, then run jobs through the RunAPI CLI.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://runapi.ai/models/nano-banana"><strong>Model Reference</strong></a> · <a href="https://github.com/runapi-ai/cli"><strong>CLI</strong></a> · <a href="https://github.com/runapi-ai/nano-banana-sdk"><strong>SDK</strong></a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<div align="center">
|
|
16
|
+
|
|
17
|
+
[](https://www.skills.sh/runapi-ai/nano-banana/nano-banana)
|
|
18
|
+
[](https://clawhub.ai/runapi-ai/runapi-nano-banana)
|
|
19
|
+
[](https://github.com/runapi-ai/nano-banana/blob/main/LICENSE)
|
|
20
|
+
|
|
21
|
+
</div>
|
|
22
|
+
<br/>
|
|
2
23
|
|
|
3
24
|
Generate and edit images with Nano Banana standard, pro, and edit models. This skill helps Claude Code, Codex, Gemini CLI, Cursor, and 50+ agents integrate Nano Banana through RunAPI.
|
|
4
25
|
|
|
@@ -10,7 +31,18 @@ The canonical agent file is `skills/nano-banana/SKILL.md`.
|
|
|
10
31
|
npx skills add runapi-ai/nano-banana -g
|
|
11
32
|
```
|
|
12
33
|
|
|
13
|
-
Or
|
|
34
|
+
Or paste this prompt to your AI agent:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
Install the nano-banana skill for me:
|
|
38
|
+
|
|
39
|
+
1. Clone https://github.com/runapi-ai/nano-banana
|
|
40
|
+
2. Copy the skills/nano-banana/ directory into your
|
|
41
|
+
user-level skills directory (e.g. ~/.claude/skills/
|
|
42
|
+
for Claude Code, ~/.codex/skills/ for Codex).
|
|
43
|
+
3. Verify that SKILL.md is present.
|
|
44
|
+
4. Confirm the install path when done.
|
|
45
|
+
```
|
|
14
46
|
|
|
15
47
|
## Quick example
|
|
16
48
|
|
|
@@ -21,9 +53,9 @@ const client = new NanoBananaClient();
|
|
|
21
53
|
const result = await client.textToImage.run({
|
|
22
54
|
model: 'nano-banana',
|
|
23
55
|
prompt: 'A bowl of fruit on a wooden table, soft daylight',
|
|
24
|
-
|
|
56
|
+
aspect_ratio: '16:9',
|
|
25
57
|
});
|
|
26
|
-
const url = result.
|
|
58
|
+
const url = result.images[0].url;
|
|
27
59
|
```
|
|
28
60
|
|
|
29
61
|
## Routing
|
|
@@ -1,206 +1,79 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: nano-banana
|
|
3
|
-
description: Generate and edit images
|
|
4
|
-
documentation: https://runapi.ai/models/nano-banana
|
|
5
|
-
provider_page: https://runapi.ai/providers/google
|
|
6
|
-
catalog: https://runapi.ai/models
|
|
3
|
+
description: Generate and edit images with Nano Banana through RunAPI. Use when the user asks an agent to create, edit, or transform images with Nano Banana. Default to the RunAPI CLI for one-off generation; use SDKs only when the user is integrating RunAPI into an app or backend.
|
|
4
|
+
documentation: https://runapi.ai/models/nano-banana.md
|
|
5
|
+
provider_page: https://runapi.ai/providers/google.md
|
|
6
|
+
catalog: https://runapi.ai/models.md
|
|
7
|
+
metadata:
|
|
8
|
+
openclaw:
|
|
9
|
+
homepage: https://runapi.ai/models/nano-banana
|
|
10
|
+
requires:
|
|
11
|
+
bins:
|
|
12
|
+
- runapi
|
|
13
|
+
install:
|
|
14
|
+
- kind: brew
|
|
15
|
+
formula: runapi-ai/tap/runapi
|
|
16
|
+
bins:
|
|
17
|
+
- runapi
|
|
18
|
+
envVars:
|
|
19
|
+
- name: RUNAPI_API_KEY
|
|
20
|
+
required: false
|
|
21
|
+
description: Optional RunAPI API key; agents should prefer environment auth or saved CLI config. Browser login is interactive fallback only.
|
|
7
22
|
---
|
|
8
|
-
# @runapi.ai/nano-banana — RunAPI.ai Nano Banana image generation
|
|
9
23
|
|
|
10
|
-
|
|
24
|
+
# Nano Banana on RunAPI
|
|
11
25
|
|
|
12
|
-
|
|
26
|
+
Generate and edit images with Nano Banana through RunAPI. The default path for one-off agent tasks is the `runapi` CLI; SDKs are for application integration.
|
|
13
27
|
|
|
14
|
-
|
|
28
|
+
## Routing decision
|
|
15
29
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Set your API key in the environment:
|
|
21
|
-
|
|
22
|
-
```dotenv
|
|
23
|
-
# .env
|
|
24
|
-
RUNAPI_API_KEY=runapi_xxx # get one at https://runapi.ai/settings/api_keys
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
```ts
|
|
28
|
-
import { NanoBananaClient } from '@runapi.ai/nano-banana';
|
|
29
|
-
|
|
30
|
-
// The SDK reads RUNAPI_API_KEY from the environment automatically.
|
|
31
|
-
const client = new NanoBananaClient();
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
Pass `{ apiKey }` explicitly if you manage secrets differently. `baseUrl` defaults to `https://runapi.ai`; override only for local development.
|
|
35
|
-
|
|
36
|
-
## Core recipe — text to image
|
|
37
|
-
|
|
38
|
-
```ts
|
|
39
|
-
const result = await client.textToImage.run({
|
|
40
|
-
model: 'nano-banana',
|
|
41
|
-
prompt: 'A bowl of fruit on a wooden table, soft daylight',
|
|
42
|
-
image_size: '16:9',
|
|
43
|
-
});
|
|
44
|
-
|
|
45
|
-
const url = result.result_urls[0];
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
`run()` creates the task, auto-polls, and resolves only when the task completes — `result_urls[0]` is guaranteed on the resolved value. On failure it throws `TaskFailedError`; on polling timeout it throws `TaskTimeoutError`. Use `run()` for scripts and short-lived processes. For request handlers, split it:
|
|
49
|
-
|
|
50
|
-
```ts
|
|
51
|
-
const { id } = await client.textToImage.create({ model: 'nano-banana', prompt: '...' });
|
|
52
|
-
// return 202 immediately; fetch later:
|
|
53
|
-
const status = await client.textToImage.get(id);
|
|
54
|
-
if (status.status === 'completed') { /* ... */ }
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Do not hold a web worker open waiting on `run()`. Split + webhook is the production pattern.
|
|
58
|
-
|
|
59
|
-
`run()` polls every 2 s for up to 15 min by default. Tune when needed:
|
|
60
|
-
|
|
61
|
-
```ts
|
|
62
|
-
await client.textToImage.run(params, { maxWaitMs: 5 * 60_000, pollIntervalMs: 2_000 });
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
If `TaskTimeoutError` fires, the task is still running server-side — resume with `textToImage.get(id)` or finish via webhook.
|
|
66
|
-
|
|
67
|
-
## Pro model — higher fidelity + resolution
|
|
30
|
+
- One-off generation, editing, or transformation for the user → use the **CLI path** with the `runapi` binary.
|
|
31
|
+
- Building an app, backend, worker, library, or production codebase → use the **SDK integration path**.
|
|
68
32
|
|
|
69
|
-
|
|
70
|
-
const result = await client.textToImage.run({
|
|
71
|
-
model: 'nano-banana-pro',
|
|
72
|
-
prompt: 'A futuristic city skyline at dusk',
|
|
73
|
-
aspect_ratio: '16:9', // pro uses aspect_ratio, not image_size
|
|
74
|
-
resolution: '2K', // 1K | 2K | 4K
|
|
75
|
-
output_format: 'jpeg',
|
|
76
|
-
});
|
|
77
|
-
```
|
|
33
|
+
## CLI path
|
|
78
34
|
|
|
79
|
-
|
|
35
|
+
The `runapi` binary is the runtime dependency. Run `runapi auth status` first. For agents and headless runs, prefer `RUNAPI_API_KEY` or import it into saved config with `printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -`. Use `runapi login` only when the user explicitly wants interactive browser auth.
|
|
80
36
|
|
|
81
|
-
|
|
37
|
+
Inspect the available commands and request fields with CLI help:
|
|
82
38
|
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
prompt: '...up to 20,000 characters, with up to 14 reference images...',
|
|
87
|
-
aspect_ratio: '1:8', // v2 adds extreme ratios 1:4, 1:8, 4:1, 8:1
|
|
88
|
-
resolution: '2K', // 1K | 2K | 4K (billed 16¢ / 24¢ / 36¢)
|
|
89
|
-
output_format: 'jpg',
|
|
90
|
-
});
|
|
39
|
+
```shell
|
|
40
|
+
runapi nano-banana --help
|
|
41
|
+
runapi nano-banana text-to-image --help
|
|
91
42
|
```
|
|
92
43
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
```ts
|
|
96
|
-
const edited = await client.editImage.run({
|
|
97
|
-
model: 'nano-banana-edit',
|
|
98
|
-
prompt: 'Make it look like a watercolor painting',
|
|
99
|
-
image_urls: ['https://cdn.example.com/source.jpg'],
|
|
100
|
-
image_size: '1:1',
|
|
101
|
-
});
|
|
44
|
+
Run a one-off task (synchronous — polls until the task completes):
|
|
102
45
|
|
|
103
|
-
|
|
46
|
+
```shell
|
|
47
|
+
runapi nano-banana text-to-image --input-file request.json
|
|
104
48
|
```
|
|
105
49
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
| `model` | Params | Use case |
|
|
109
|
-
|---|---|---|
|
|
110
|
-
| `nano-banana` | `image_size`, `image_input?` | Base text-to-image / image-guided. |
|
|
111
|
-
| `nano-banana-pro` | `aspect_ratio`, `resolution`, `image_input?` | Higher fidelity, 1K/2K/4K. |
|
|
112
|
-
| `nano-banana-2` | `aspect_ratio`, `resolution`, `image_input?` | V2: long prompts (≤20k chars), ≤14 reference images, extra aspect ratios. |
|
|
113
|
-
| `nano-banana-edit` | `image_urls`, `image_size` | Prompt-driven edit of a source image. |
|
|
114
|
-
|
|
115
|
-
`image_size` / `aspect_ratio` values (base / pro): `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `auto`. V2 adds `1:4`, `1:8`, `4:1`, `8:1`. `output_format`: `png` / `jpg` / `jpeg`.
|
|
116
|
-
|
|
117
|
-
Exact credit costs per model are shown at https://runapi.ai/pricing and in the dashboard — do not hardcode prices in application code.
|
|
118
|
-
|
|
119
|
-
## Callbacks (webhooks)
|
|
50
|
+
Submit asynchronously and poll separately:
|
|
120
51
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
await client.textToImage.create({
|
|
125
|
-
model: 'nano-banana',
|
|
126
|
-
prompt: '...',
|
|
127
|
-
callback_url: 'https://your.app/webhooks/runapi/nano-banana',
|
|
128
|
-
});
|
|
52
|
+
```shell
|
|
53
|
+
runapi nano-banana text-to-image --async --input-file request.json
|
|
54
|
+
runapi wait <task-id> --service nano-banana --action text-to-image
|
|
129
55
|
```
|
|
130
56
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
```ts
|
|
134
|
-
{ id: string; status: 'completed' | 'failed'; result_urls?: string[]; error?: string }
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
**Always verify the signature before trusting the body.** RunAPI signs every callback with your account's Callback Secret (rotate at `/accounts/callback_secret`). Headers:
|
|
138
|
-
|
|
139
|
-
- `X-Callback-Id` — UUID, store to make handler idempotent
|
|
140
|
-
- `X-Callback-Timestamp` — unix seconds, reject if `|now - ts| > 300`
|
|
141
|
-
- `X-Callback-Signature` — base64 HMAC-SHA256 over `` `${id}.${ts}.${rawBody}` `` using the base64-decoded secret
|
|
142
|
-
|
|
143
|
-
```ts
|
|
144
|
-
import crypto from 'node:crypto';
|
|
145
|
-
|
|
146
|
-
function verify(raw: string, id: string, ts: string, sig: string, secret: string) {
|
|
147
|
-
const key = Buffer.from(secret, 'base64');
|
|
148
|
-
const mac = crypto.createHmac('sha256', key)
|
|
149
|
-
.update(`${id}.${ts}.${raw}`)
|
|
150
|
-
.digest('base64');
|
|
151
|
-
return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig));
|
|
152
|
-
}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Reply `2xx` within 10s; any non-2xx triggers retries.
|
|
156
|
-
|
|
157
|
-
## Errors
|
|
158
|
-
|
|
159
|
-
All errors are re-exported from `@runapi.ai/core`. Always `instanceof` — never string-match messages.
|
|
160
|
-
|
|
161
|
-
| Error | Status | Action |
|
|
162
|
-
|---|---|---|
|
|
163
|
-
| `AuthenticationError` | 401 | abort; surface "reconnect your API key" |
|
|
164
|
-
| `InsufficientCreditsError` | 402 | prompt user to top up at runapi.ai/billing |
|
|
165
|
-
| `ValidationError` | 400 / 422 | fix params; do not retry |
|
|
166
|
-
| `RateLimitError` | 429 | sleep `err.retryAfterMs`, then retry |
|
|
167
|
-
| `ServiceUnavailableError` | 503 / 455 | retry with backoff; transient service issue |
|
|
168
|
-
| `TaskFailedError` | — | show `err.details` to user; do not auto-retry |
|
|
169
|
-
| `TaskTimeoutError` | — | re-poll with `<resource>.get(id)` |
|
|
170
|
-
|
|
171
|
-
```ts
|
|
172
|
-
import { InsufficientCreditsError, TaskFailedError } from '@runapi.ai/nano-banana';
|
|
173
|
-
|
|
174
|
-
try {
|
|
175
|
-
await client.textToImage.run({ model: 'nano-banana', prompt: '...' });
|
|
176
|
-
} catch (err) {
|
|
177
|
-
if (err instanceof InsufficientCreditsError) { /* surface top-up CTA */ }
|
|
178
|
-
else if (err instanceof TaskFailedError) { /* show err.details */ }
|
|
179
|
-
else throw err;
|
|
180
|
-
}
|
|
181
|
-
```
|
|
57
|
+
Available commands: `text-to-image`, `edit-image`.
|
|
182
58
|
|
|
183
|
-
##
|
|
59
|
+
## SDK integration path
|
|
184
60
|
|
|
185
|
-
-
|
|
186
|
-
- The base model uses **`image_size`**; pro and v2 use **`aspect_ratio`**. They are different fields — do not substitute one for the other.
|
|
187
|
-
- `resolution` (`1K` / `2K` / `4K`) applies to `nano-banana-pro` and `nano-banana-2`.
|
|
188
|
-
- EditImage (`editImage.run`) require `image_urls` (an array), not `image_input`.
|
|
189
|
-
- Response uses `result_urls` (an array of URL strings), not `images` or `videos`.
|
|
190
|
-
- `callback_url` must be reachable from the public internet. `localhost` / `127.0.0.1` URLs will never fire — use a tunnel (cloudflared, ngrok, tailscale funnel) when developing locally.
|
|
61
|
+
When integrating Nano Banana into an app, backend, worker, or library — not for one-off tasks — use a RunAPI SDK package:
|
|
191
62
|
|
|
192
|
-
|
|
63
|
+
- JavaScript / TypeScript: `@runapi.ai/nano-banana`
|
|
64
|
+
- Ruby: `runapi-nano_banana`
|
|
65
|
+
- Go: `github.com/runapi-ai/nano-banana-sdk/go`
|
|
193
66
|
|
|
194
|
-
|
|
67
|
+
## References
|
|
195
68
|
|
|
196
|
-
|
|
69
|
+
- Model overview, pricing, and rate limits: https://runapi.ai/models/nano-banana.md
|
|
70
|
+
- Provider comparison: https://runapi.ai/providers/google.md
|
|
71
|
+
- Full model catalog: https://runapi.ai/models.md
|
|
197
72
|
|
|
198
|
-
|
|
73
|
+
## Variants
|
|
199
74
|
|
|
200
|
-
|
|
201
|
-
- [
|
|
202
|
-
- [
|
|
203
|
-
- [
|
|
204
|
-
- [Nano Banana 2](https://runapi.ai/models/nano-banana/2)
|
|
75
|
+
- [Standard](https://runapi.ai/models/nano-banana/nano-banana.md)
|
|
76
|
+
- [Pro](https://runapi.ai/models/nano-banana/pro.md)
|
|
77
|
+
- [Edit](https://runapi.ai/models/nano-banana/edit.md)
|
|
78
|
+
- [Nano Banana 2](https://runapi.ai/models/nano-banana/2.md)
|
|
205
79
|
|
|
206
|
-
Compare Nano Banana with other Google models at https://runapi.ai/providers/google. Browse every RunAPI model and skill at https://runapi.ai/models. SDK repository: https://github.com/runapi-ai/nano-banana-sdk. Skill repository: https://github.com/runapi-ai/nano-banana.
|